agency

Agency

Governed AI agents with isolated runtimes, mediated execution, durable memory, and audit trails you can inspect.

Agency is the reference implementation of ASK, the open framework for agent security.

What Agency Is

Agency runs one or a few AI agents in isolated microVM workspaces. Agents can work with files, tools, and model providers without being handed your host, your network, or your credentials.

The product is the governed runtime around the agent:

• isolated per-agent workspaces
• external enforcement and mediated egress
• direct-message workflow for normal use
• graph-backed context and durable memory
• visible budget, usage, and audit records
• REST, OpenAPI, CLI, web, and MCP surfaces

The current core is intentionally focused. Broader platform work exists in the repo, but the default story is governed single-agent and small-agent workflows that are observable, interruptible, and recoverable.

How It Works

The Go gateway is the control plane and source of truth. Operators use the CLI, web UI, REST API, or MCP server. The web UI is a REST client.

Each agent runs in its own microVM workspace through microagent. An external per-agent enforcer mediates model calls, tool calls, service access, and egress. Real provider credentials stay outside the agent runtime.

Agency follows the ASK cognitive model:

• Constraints are operator-owned and read-only
• Identity is agent-owned and durable
• Session is ephemeral per run

Agency is event-driven. Direct messages, platform events, and routed work wake agents when there is work to do; broad polling loops are not the default model.

Quick Start

Install with Homebrew:

brew tap geoffbelknap/tap
brew install agency

Or use the one-shot installer:

curl -fsSL https://geoffbelknap.github.io/agency/install.sh | bash

Then run:

agency quickstart

Quickstart guides you through provider setup, credential storage, infrastructure startup, first-agent creation, and opening the direct-message chat.

After setup, the main loop is:

agency send henry "summarize the open issues in this repo"
agency log henry
agency admin doctor

See docs/quickstart.md for the full guided flow.

Requirements

Agency uses microagent for agent workspaces:

• Linux and WSL2 use Firecracker and need KVM plus vsock access
• macOS Apple silicon uses Apple's Virtualization framework
• Windows is supported through WSL2

On Linux and WSL2, check KVM access before first run:

test -r /dev/kvm && test -w /dev/kvm

If /dev/kvm is owned by root:kvm and that command fails, add your user to the kvm group:

sudo usermod -aG kvm $USER

On regular Linux, log out and back in. On WSL2, run this from Windows and then reopen the distro:

wsl.exe --shutdown

Agency also needs:

• an API key from at least one supported model provider
• mitmdump and Agency's egress addon dependencies for host-managed egress mediation
• e2fsprogs / mke2fs for microVM root filesystem creation
• Node/npm only when building the web UI from source

Packaged installs run the host dependency helper automatically. From a source checkout you can verify or install host dependencies with:

./scripts/install/host-dependencies.sh --check
./scripts/install/host-dependencies.sh

Runtime Artifacts

The supported release path is Agency on microagent. Docker, Podman, containerd, direct Firecracker, direct apple-vf-microvm, and Apple Container execution backends are legacy adapter paths, not selectable runtime backends.

Dockerfiles remain in the repo as OCI filesystem recipes. MicroVM rootfs inputs must be explicit, versioned OCI artifact references. Release publishing emits:

• ghcr.io/geoffbelknap/agency-runtime-body:vX.Y.Z
• ghcr.io/geoffbelknap/agency-runtime-enforcer:vX.Y.Z

Source checkouts can validate the supported path with versioned artifacts:

./scripts/readiness/microvm-smoke.sh \
  --backend microagent \
  --rootfs-oci-ref ghcr.io/geoffbelknap/agency-runtime-body:vX.Y.Z \
  --enforcer-oci-ref ghcr.io/geoffbelknap/agency-runtime-enforcer:vX.Y.Z

Programmatic Surface

Agency exposes the same platform contract to the CLI, web UI, AI assistants, and third-party clients:

• REST API on localhost:8200
• canonical OpenAPI spec in internal/api/openapi.yaml
• supported default API view at /api/v1/openapi-core.yaml
• MCP server through agency mcp-server

Core runtime/operator endpoints include: