agent-assembly

agent-assembly is the open-source core of the AI Agent Assembly governance platform. It enforces policy on AI agents — what they may call, spend, and connect to — and records every decision it makes in a hash-chained, tamper-evident audit trail (unkeyed SHA-256, JSONL sink only, retention deletes rows — see Audit).

This book is the contributor and operator reference for the core. If you build with a language SDK instead, read the per-SDK guides below.

New here? Start with the Introduction — it explains what Agent Assembly is, the problem it solves, the core concepts, and the three-layer interception model. Then move on to the Quick Start.

Other docs: Docs Hub · Python SDK · Node SDK · Go SDK

Run it locally

Point the gateway at a bundled reference policy and you have a governing daemon listening on 127.0.0.1:50051:

git clone https://github.com/ai-agent-assembly/agent-assembly.git
cd agent-assembly
cargo run -p aa-gateway -- --policy policy-examples/low-risk.yaml

From there, attach an SDK shim, the aa-proxy sidecar, or the eBPF layer to start intercepting agent actions. The Architecture chapter explains how those three layers fit together.

Where to go next

Audience

This book targets contributors and operators of agent-assembly. SDK users (Python, TypeScript, Go) should refer to the per-SDK guides in the sibling repositories.

See also

• README — top-level project overview, prerequisites, quickstart
• CONTRIBUTING — development workflow, branch naming, PR rules
• API reference — generate locally with cargo doc --workspace --no-deps --open

Diagram rendering

This book renders Mermaid diagrams via the mdbook-mermaid preprocessor:

graph LR
    SDK[SDK shim] --> Gateway[aa-gateway]
    Proxy[aa-proxy] --> Gateway
    eBPF[aa-ebpf] --> Gateway
    Gateway --> Audit[(Audit log)]

Introduction

agent-assembly is a governance and security runtime for AI agents. It sits between an agent and the tools, models, and networks it reaches for, evaluates the actions routed to it against policy and budget, and records the outcome in a hash-chained audit trail. It is the open-source core of the AI Agent Assembly platform.

This section is the place to start. It explains what the runtime is and the problem it solves, defines the handful of core concepts the rest of the book assumes, and gives a teaser of the three-layer interception model that widens what the runtime can see, depending on how the agent is built and launched.

Read the pages in order:

When you are ready to run something, jump to the Quick Start. For the security rationale behind the design, read the Security Model; for the crate-level implementation, read Architecture.

What Agent Assembly is & the problem

In plain terms. AI agents act on their own — they run tools, call services, and spend money to get a job done. Agent Assembly is the set of guardrails around them: for each action that reaches it, it checks the action against rules you define, allows or blocks it before it happens, and keeps a permanent record of what was decided. Think of it as a security checkpoint on the paths you route through it — which means the paths you leave unrouted still need their own controls. Which actions reach the checkpoint depends on how the agent is wired up; the three-layer model explains what each layer does and does not see, and Limitations and known bypasses states the gaps that remain today.

It is for the people responsible for those agents — developers wiring them up, security and operations teams keeping them safe, and the planners who need to know the controls exist. With it you can decide which tools an agent may use, stop it from leaking data or overspending, and review exactly what was observed and decided.

What it is

agent-assembly is a governance-native runtime for AI agents. An AI agent — an LLM wired up to tools, APIs, shells, and network access — is given a goal and then decides, on its own, which actions to take to reach it. Agent Assembly governs those actions. Each time a governed action reaches the runtime — a tool call the SDK wraps, an outbound request routed through the proxy, a model call on an inspected host — the runtime evaluates that action against a policy and a budget, returns allow or deny before the action runs, and writes a hash-chained audit record of the decision. Actions that reach none of those interception points are neither evaluated nor recorded.

A governing gateway, pointed at a reference policy, is one command away:

cargo run -p aa-gateway -- --policy policy-examples/low-risk.yaml

That daemon listens on 127.0.0.1:50051 and is ready for any interception layer to connect. The rest of this book explains how to put it to work.

The problem: ungoverned agent tool-use is risky

A traditional program does exactly what its code says. An AI agent does not. It plans its own steps at runtime, so the set of actions it might take is open-ended and not knowable in advance. The moment you give an agent real capabilities — the ability to run shell commands, hit internal APIs, call third-party services, read files, or pay for tokens — that open-endedness becomes a concrete risk:

• Unbounded tool-use. An agent can invoke any tool it has been handed, in any order, with any arguments it constructs. A prompt-injected or simply confused agent may call a destructive tool it was never meant to use.
• Data exfiltration. An agent that can both read sensitive data and reach the network can leak that data — intentionally coerced by an attacker, or by accident — over an outbound request. Secrets and credentials are the highest-value target.
• Runaway spend. Agents loop. A planning loop that retries, fans out, or gets stuck can burn through an LLM budget in minutes with no natural stopping point.
• No accountability. When an agent does something it should not have, teams need to answer what did it do, when, and was it allowed? Without a tamper- evident record of every decision, that question has no answer.
• Bypass. Controls that live only inside the agent’s own code are only as trustworthy as the agent. An agent that skips the SDK, or is compromised, slips past anything that depended on its cooperation.

These risks are not hypothetical edge cases — they are the default behavior of a capable agent with no guardrails. Restricting the model’s prompt is not enough, because the model is exactly the component you cannot fully trust.

The value proposition

Agent Assembly turns “trust the agent to behave” into “the runtime enforces what the agent may do.” It provides:

• Policy enforcement at the action boundary. Allow/deny decisions are made by a central gateway before an action executes, driven by declarative policy rather than agent cooperation.
• Budget control. Per-team spend is tracked and enforced; a request that would breach the budget is denied, so a runaway loop is stopped, not just reported after the fact.
• A hash-chained audit trail. Every decision the runtime makes — allow and deny alike — is recorded, giving teams a tamper-evident account of the agent behavior that was observed, for debugging, incident response, and compliance. Tamper-evident is not immutable: the SHA-256 chain is unkeyed, covers the JSONL sink only, and retention pruning deletes rows. See Audit.
• Defense that does not depend on the agent’s cooperation. Enforcement is layered across three independent interception points (see the three-layer model), so governance can still hold when an agent skips its SDK. Each layer has its own precondition, so the layers narrow the gap rather than eliminating it.

Crucially, the agent does not have to cooperate on the paths that are wired up: governance is enforced around the agent, by infrastructure the agent does not control. What that does not mean is universal mediation — an action on a path no deployed layer observes is not governed, and a tool launched outside the managed path is a demonstrated example. The Security Model section makes the trust boundaries explicit, and Limitations and known bypasses states what is unmeasured or unsupported today.

Who this book is for

This book is the reference for contributors and operators of the agent-assembly core — people running the gateway, writing policy, and deploying the interception layers. If you are instead building an application with a language SDK, start from the per-SDK guides: Python SDK, Node SDK, Go SDK.

Last updated: 2026-08-06 by Chisanan232

Core concepts

Four concepts recur throughout this book. Understanding them here makes every later chapter easier to read.

Agent

An agent is the workload being governed: an LLM-driven program that decides, at runtime, which actions to take to accomplish a goal. From the runtime’s point of view an agent is an identity that performs actions — calling a tool, making an LLM request, or reaching out over the network. Agents register with the gateway and are organized under a team and an org, which is the scope at which policy and budget are applied.

Each governed action is described by an action type (for example, a tool call or an LLM call), a target (what it is acting on), and a set of labels (metadata used by policy rules). This is the unit the runtime makes a decision about.

Policy

A policy is a declarative document — written in YAML or TOML — that states what agents are and are not allowed to do. Rules match on the action type, target, and labels of a request and resolve to allow or deny.

Policies are scoped and they cascade. Rules can be attached at the org, team, agent, and tool levels; when an action is evaluated, the gateway walks those scopes and merges them with a most-restrictive-wins rule, so a broad organizational deny cannot be loosened by a narrower scope. Policy is evaluated server-side, in the gateway — never by the agent or a dashboard — so the decision cannot be tampered with by the workload it governs. The reference policies under policy-examples/ are a good starting point. The detailed evaluation path is documented in Architecture.

Budget

A budget caps how much a team may spend on agent activity, primarily the cost of LLM calls. The gateway tracks consumption per team against a cost model and treats the budget as part of the policy decision: a request that would breach the budget is downgraded from allow to deny. This makes budget a hard guardrail that stops runaway spend in the moment, rather than a billing report that arrives after the money is gone.

Audit

The audit trail is the hash-chained record of the decisions the gateway makes — both allows and denies — together with the action that prompted it. Each entry in the per-session JSONL log carries an unkeyed SHA-256 digest over its own fields plus the preceding entry’s digest, and aasm audit verify-chain re-walks it, so careless alteration is detectable. Read the guarantee precisely: the chain is tamper-evident, not tamper-proof and not immutable — it is unkeyed, so it is not a signature; it covers the JSONL sink only, and the database mirror stores no chain metadata; the log is append-only by convention rather than by constraint, since retention pruning deletes rows; and emission is best-effort, so a dropped entry is indistinguishable from tampering. Within those bounds it answers the accountability question for a governed agent: what did it do, when, and was it permitted? Audit records use a single wire format regardless of which interception layer observed the action, so the gateway presents one unified history. Audit data underpins debugging, incident response, and compliance export.

With these four in hand — agents perform actions, policy decides allow/deny, budget caps spend, and audit records each evaluated action — the three- layer interception model explains how the runtime actually sees an agent’s actions in order to govern them.

Last updated: 2026-08-06 by Chisanan232

The three-layer interception model at a glance

To govern an action, the runtime first has to see it. Agent Assembly intercepts agent actions at three independent layers, each catching what the layers above it might miss, and routes every observed action to one central gateway for a decision. This page is a teaser; the Security Model covers why the layers are arranged this way and what each defends against, and Architecture covers how each is implemented.

The three layers

The layers are ordered by a deliberate trade-off — lowest latency first, highest detection authority first:

The latency-vs-authority trade-off is the key idea. The in-process SDK is the cheapest place to make a decision, but it is also the easiest for an agent to avoid — it lives inside the very process you do not fully trust. The eBPF layer is the most expensive to run, but it watches from the kernel, below anything the agent can reach, so it can report actions the higher layers never saw — including deliberate attempts to bypass the SDK.

Note the distinction the table draws, because it decides what each layer can promise: layer 2 denies an action before it runs; layer 1 evaluates before the call but is advisory — aa-sdk-client has no in-tree caller that refuses, and a non-cooperating process simply never asks it (aa-sdk-client/src/decision.rs:32-33, ADR 0002); layer 3 reports what it observed. Its probes emit telemetry and return no verdict, so an action it sees is an action that already happened.

How they compose

The layers are not alternatives; they stack. A deployment runs whatever subset fits its constraints, and because every layer reports to the same gateway using the same audit wire format, the gateway sees one unified view no matter which layers produced the events. Coverage is the union of the layers you deploy: the SDK handles the fast common path, the proxy backstops network egress without touching agent code, and eBPF is the observation floor that reports what slipped past both.

Running all three narrows the gap; it does not close it. Coverage is still bounded by each layer’s own preconditions — an action escapes governance entirely if it is not a wrapped tool call, is not routed through the proxy, and either does not use OpenSSL or does not run on a Linux host with the eBPF layer loaded. The known limitations page enumerates the residual gaps, split into the ones that have been demonstrated and the ones that are inferred.

graph TD
    classDef agent fill:#eef2ff,stroke:#6366f1
    classDef l1 fill:#eaf6ee,stroke:#3aa55b
    classDef l2 fill:#fff3d6,stroke:#c98a00
    classDef l3 fill:#fdecea,stroke:#d75748
    classDef gw fill:#e8f1ff,stroke:#5b8def

    Agent["AI agent<br/>(tool / LLM / network calls)"]:::agent

    subgraph Interception["Three interception layers"]
        L1["Layer 1 — SDK shim<br/>in-process · lowest latency"]:::l1
        L2["Layer 2 — Sidecar proxy<br/>aa-proxy · outbound HTTPS"]:::l2
        L3["Layer 3 — eBPF<br/>kernel · highest authority"]:::l3
    end

    GW["Gateway (aa-gateway)<br/>policy · budget · decision"]:::gw
    Audit[("Hash-chained audit log")]

    Agent -->|"action"| L1
    Agent -.->|"network egress"| L2
    Agent -.->|"syscalls / TLS"| L3

    L1 -->|"allow / deny request"| GW
    L2 -->|"allow / deny request"| GW
    L3 -->|"audit-only events"| GW

    GW -->|"ALLOW / DENY"| Agent
    GW --> Audit

The gateway is the single brain behind all three: it holds the agent registry, evaluates policy, enforces budgets, and appends the audit record before answering allow or deny.

Where to go next

• Security Model — the threat model and why this layered defense closes the gaps, including what each layer is and is not trusted to do.
• Architecture — the crate-level how: the gateway, the policy engine, the transports, and the full interception data flow.

Last updated: 2026-08-06 by Chisanan232

Requirements

Before you install Agent Assembly, make sure your machine meets the prerequisites below. The CLI and the governing gateway run on macOS and Linux; only the kernel-level eBPF interception layer is Linux-only.

At a glance

Supported platforms

The three interception layers have different platform reach. The SDK shim and the sidecar proxy (aa-proxy) run anywhere the runtime builds; kernel-level eBPF interception is Linux-only.

On macOS, governance is enforced through the SDK and proxy layers; the eBPF layer is unavailable. See aa-ebpf/README.md for kernel requirements.

Installing the CLI only

If you just want the aasm operator CLI from a published release, you need nothing more than a supported OS. The quick-install script downloads a pre-built binary for x86_64/aarch64 on macOS (apple-darwin) and Linux (unknown-linux-gnu). Jump straight to Installation.

Building from source

To build the Cargo workspace yourself — for development, or to run the gateway via cargo run — install the following.

Required

• Rust stable, ≥ 1.75 — install via rustup. The workspace uses the 2021 edition.
• protoc — the Protocol Buffers compiler, required by the aa-proto and aa-gateway build scripts.
  • macOS: brew install protobuf
  • Debian / Ubuntu: apt-get install protobuf-compiler

Recommended developer tooling

These are not needed to run the CLI but are used by the test and contribution workflow:

• cargo-nextest — the test runner used across the workspace.
• cargo-deny — dependency and license checks.
• Lefthook — git pre-commit / pre-push hooks.

Linux-only build dependencies

On Linux, the native-TLS path in aa-proxy additionally requires:

• pkg-config
• libssl-dev (Debian/Ubuntu) or openssl-devel (RHEL-family)

Requirements per interception layer

Each interception layer can be deployed independently. Pick the layers you need and install only their requirements.

The eBPF caveat. The aa-ebpf-probes and aa-ebpf-programs crates compile for the bpfel-unknown-none target and are intentionally outside the host Cargo workspace. They cannot be selected with cargo -p and do not build on macOS. If you are on macOS, you can still run and govern agents through the SDK and proxy layers — you simply do not get the kernel-level layer.

Next

With the prerequisites in place, continue to Installation.

Last updated: 2026-08-06 by Chisanan232

Installation

This page covers every supported way to get the aasm CLI onto your machine, then how to verify it works. Pick one method:

Alpha note. Agent Assembly is in the v0.0.1 pre-release series; published releases are GitHub pre-releases. The public API and wire protocol are not yet stable — do not use in production.

curl -sSf https://agent-assembly.com/install.sh | sh

export PATH="$HOME/.local/bin:$PATH"

# Install a specific release tag (default: latest)
AASM_VERSION=v0.0.1-rc.6 curl -sSf https://agent-assembly.com/install.sh | sh

# Install to a custom directory
AASM_INSTALL_DIR=/usr/local/bin curl -sSf https://agent-assembly.com/install.sh | sh

AASM_REQUIRE_SIGNATURE=1 curl -sSf https://agent-assembly.com/install.sh | sh

brew install ai-agent-assembly/tap/aasm

VERSION=v0.0.1-rc.6
ASSET=aasm-aarch64-apple-darwin.tar.gz   # adjust for your platform
BASE="https://github.com/ai-agent-assembly/agent-assembly/releases/download/${VERSION}"

curl -sSfL "${BASE}/${ASSET}"        -o "${ASSET}"
curl -sSfL "${BASE}/SHA256SUMS"      -o SHA256SUMS

# Verify the checksum (use sha256sum on Linux, shasum -a 256 on macOS)
shasum -a 256 -c <(grep "${ASSET}" SHA256SUMS)

# (Optional) Verify the cosign signature on the checksum file
curl -sSfL "${BASE}/SHA256SUMS.cosign.bundle" -o SHA256SUMS.cosign.bundle
cosign verify-blob \
  --bundle SHA256SUMS.cosign.bundle \
  --certificate-identity-regexp '^https://github\.com/ai-agent-assembly/agent-assembly/\.github/workflows/release\.yml@refs/tags/v.*$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  SHA256SUMS

tar -xzf "${ASSET}" aasm
install -m755 aasm ~/.local/bin/aasm

git clone https://github.com/ai-agent-assembly/agent-assembly.git
cd agent-assembly
cargo build -p aa-cli            # produces ./target/debug/aasm

cargo install --path aa-cli      # installs `aasm` into ~/.cargo/bin

Verify the install

Confirm the binary is on your PATH and runs:

$ aasm --version
aasm 0.0.1-rc.6

A fuller report — the CLI version plus whether a gateway and API are reachable — comes from aasm version. With no control plane running yet, both report unreachable, which is expected at this point:

$ aasm version
+-----------+---------------+-------------+
| COMPONENT | VERSION       | STATUS      |
+=========================================+
| cli       | 0.0.1-rc.6    | -           |
|-----------+---------------+-------------|
| gateway   | -             | unreachable |
|-----------+---------------+-------------|
| api       | -             | unreachable |
+-----------+---------------+-------------+

List the available commands with aasm --help:

$ aasm --help
aasm — command-line tool for Agent Assembly

Usage: aasm [OPTIONS] <COMMAND>

Commands:
  admin       Gateway administrative operations
  agent       Manage monitored agent processes
  alerts      Manage governance alerts
  audit       Query audit log entries and export compliance reports
  ...
  status      Show fleet health, agents, approvals, and budget at a glance
  topology    Visualize agent topology, trees, lineage, and statistics
  gateway     Manage the aa-gateway governance daemon — agent registry, policy engine, audit log
  start       Start the locally-managed Agent Assembly gateway process
  version     Show CLI and gateway version information
  ...

Troubleshooting

Next

Now configure the CLI to talk to your gateway — see Configuration.

Last updated: 2026-07-23 by Bryant

Configuration

The aasm CLI works with zero configuration — if you never create a config file, it talks to a gateway API at http://localhost:8080. This page covers the config file format, named contexts (connection profiles), the environment variables the CLI reads, and the separate agent-assembly.toml runtime config the gateway consumes.

Where the CLI connects, and how it decides

Every CLI command that talks to the control plane resolves three things — the API URL, an optional API key, and an output format — from the following sources, highest priority first:

1. Explicit flags: --api-url, --api-key.
2. A named context selected with --context <name>, or the default_context from the config file.
3. The built-in default API URL: http://localhost:8080.

So aasm status with no flags and no config file connects to http://localhost:8080. A --api-url flag always wins over any context.

The CLI config file: ~/.aa/config.yaml

CLI configuration lives at ~/.aa/config.yaml. The file is optional; if it is absent the CLI uses defaults. Its schema:

# Name of the context used when --context is not given (optional).
default_context: local

# Named connection profiles. Each has an api_url and an optional api_key.
contexts:
  local:
    api_url: http://localhost:8080
  production:
    api_url: https://api.example.com
    api_key: secret123        # optional; omit for unauthenticated endpoints

# Settings for `aasm dashboard start` (optional; shown with defaults).
dashboard:
  port: 3000
  auto_open: false

Named contexts (connection profiles)

A context is a named API URL + key, so you can switch between, say, a local gateway and a hosted one without retyping flags. Manage contexts with aasm context; the commands read and write ~/.aa/config.yaml for you.

Create or update contexts:

$ aasm context set local --api-url http://localhost:8080
Context 'local' saved.

$ aasm context set production --api-url https://api.example.com --api-key secret123
Context 'production' saved.

Choose the default context:

$ aasm context use local
Switched to context 'local'.

List them (the * marks the default; keys are never printed, only flagged as set):

$ aasm context list
local *  http://localhost:8080
production  https://api.example.com (key set)

Once a default is set, every command uses it. Override per-invocation with --context:

aasm status                       # uses default context (local)
aasm status --context production  # one-off against production
aasm status --api-url http://localhost:9090   # ad-hoc URL, ignores contexts

Environment variables

The CLI reads these environment variables. Where one overlaps a flag or config value, the precedence is noted.

Pass the API key through the environment, not the command line. --api-key puts the operator bearer token into argv, where it is readable by any local user via ps and /proc/<pid>/cmdline, and where your shell will persist it to history. AASM_API_KEY avoids all three. The flag still takes precedence when both are set, so existing scripts keep working — but a script that sets the variable is the one to write.

The prefixes are a rough guide, not a rule: AASM_* is mostly the CLI surface and AA_* mostly the daemons the CLI launches. AASM_STATE_DIR is the clear exception — it names one state root shared by the CLI, the proxy and the dev-tool integration receipt store, so treat the prefix as a hint and the “Used by” column as the answer.

AASM_STATE_DIR and the integration receipt store

AASM_STATE_DIR (default ~/.aasm) is where Agent Assembly keeps local state that is not configuration: the managed-gateway PID file, the installer’s self-copy that aasm uninstall forwards to, the proxy’s per-integration MitM host lists, and the Developer Integration receipts under ${AASM_STATE_DIR:-~/.aasm}/integrations/.

A receipt names every file Agent Assembly governs on this host, which mechanism it relies on, and where the trust material sits — a useful map for anyone planning to defeat the integration. So the directory is held to 0700 and each file to 0600, and — as with the proxy’s CA loader — the mode is re-asserted on every load, not only at creation. A receipt restored from a backup or copied in with loose permissions is tightened rather than silently trusted across a restart.

The receipts deliberately do not live inside the tool’s own configuration tree: a record whose job is to say what ~/.claude/ should contain cannot itself be one of the files being described, and removal has to be able to empty that directory without deleting its own evidence.

Not a tamper control. Each receipt carries a hash over its canonical form. That catches truncated writes, partial syncs and hand-edits — a corrupt receipt is reported rather than silently misread — but it is not a MAC. Anyone with the developer’s UID can recompute it, and host-level tamper prevention is an explicit non-goal.

The Developer Integration API variables

AA_DEVINT_ENABLED, AA_DEVINT_SOCKET and AA_DEVINT_TOKEN_FILE configure the Developer Integration API — the separate Unix socket that aasm integrations and other local clients use to install and inspect dev-tool integrations. It carries no policy decisions and no agent-action traffic, and it is off by default: AA_DEVINT_ENABLED is read at runtime startup and nothing binds the socket without it.

If you relocate the socket with AA_DEVINT_SOCKET, you must preserve its permissions — a 0700 directory and a 0600 socket. They are load-bearing: with them gone the OS layer of the two-layer authentication is gone and only the capability token remains. The token file (AA_DEVINT_TOKEN_FILE) is likewise 0600, and a token in a file readable by more than its owner is refused rather than used, so a filesystem mistake cannot become a silent authentication downgrade.

AASM_CLAUDE_MANAGED_ROOT is read by shipped code but is not a configuration knob: it redirects where the Claude Code adapter addresses the administrator-managed settings file, for tests. It cannot be used to escalate — the macOS authority refuses to elevate for any target that is not the canonical managed-settings path, so a redirected root makes the write ordinary and unprivileged rather than pointing an authorized write somewhere else, and a plan that sees a non-canonical root says so in a warning.

Three similarly-named gateway-endpoint variables are distinct and not interchangeable: AA_PROXY_GATEWAY_ENDPOINT (the proxy’s upstream gateway, above), AA_GATEWAY_ENDPOINT (used by the runtime / SDK client), and AA_GATEWAY_URL (used by the Windsurf devtool). Only AA_PROXY_GATEWAY_ENDPOINT affects aasm proxy start.

aa-api server environment variables

The REST API server (aa-api) — the process the dashboard reads through — reads its own set of AA_* variables at boot. These configure the server itself, not the CLI.

Native email/password accounts also require a Postgres-backed deployment. The AA_SMTP_* and AA_AUTH_OPEN_REGISTRATION variables only take effect once native accounts are available. See Authentication.

Policy source for aa-api

aa-api reads AA_POLICY the same way aa-gateway does — routing on the shape of the path it points at — to decide what the dashboard’s capability-matrix, topology-chain, and team-policy projections display:

When AA_POLICY is unset, the projections render an honest “Unconfigured” signal rather than presenting the generated bootstrap as though it were an operator-authored policy. Point AA_POLICY at a directory to see the full cascade in the dashboard.

Trust score tuning

The dashboard’s per-agent trust score (a policy-friction score served at GET /api/v1/analytics/trust) needs no configuration to work — every tenant starts on sensible defaults. Its penalty-signal weights are optionally tunable per tenant at runtime via GET / PUT /api/v1/analytics/trust/config; there is no environment variable for it. An agent with fewer than the minimum number of governed actions shows — (not enough data) rather than a misleading number.

Output format

Most list/get commands accept --output table|json|yaml (default table). Use json or yaml for scripting:

$ aasm version --output json
[
  {
    "component": "cli",
    "version": "0.0.1-beta.4",
    "status": "-"
  },
  ...
]

Gateway runtime config: agent-assembly.toml

The CLI config above is about how the CLI connects. The gateway itself reads a separate runtime config — agent-assembly.toml — that selects its persistence backends. A starter file ships at the repo root as agent-assembly.toml.example:

# agent-assembly.toml — example runtime configuration
[storage]
policy_store       = "redis"
audit_sink         = "postgres"
session_store      = "redis"
credential_store   = "postgres"
rate_limit_counter = "redis"
lifecycle_store    = "postgres"

# Per-driver connection settings live under [storage.<driver-name>].
[storage.redis]
url = "redis://localhost:6379"

[storage.postgres]
url = "postgresql://localhost:5432/assembly"

Each storage kind names a driver (memory, redis, or postgres); the runtime resolves the name to a registered backend at boot, so you can switch backends without recompiling.

Validate it before you boot

Use aasm config validate to check an agent-assembly.toml (currently the [storage] section) before starting the gateway:

$ aasm config validate agent-assembly.toml.example
Config is valid: agent-assembly.toml.example

A valid file exits 0; an invalid one reports the problem and exits non-zero.

Next

You are configured. Walk through starting a gateway and observing an agent in First run.

Last updated: 2026-08-04 by Claude Code

First run

This walkthrough takes you from a freshly installed aasm to a running governance gateway that is ready for an agent to connect. Every command and its output below was captured from a real v0.0.1-beta.4 build.

The flow

flowchart LR
    A["aasm gateway start<br/>--policy low-risk.yaml"] --> B["gRPC gateway<br/>127.0.0.1:50051"]
    B --> C["aasm gateway status<br/>→ running"]
    C --> D{"Connect an<br/>interception layer"}
    D -->|SDK shim| E["Agent registers<br/>via gRPC"]
    D -->|Sidecar proxy| E
    D -->|eBPF on Linux| E
    E --> F["aasm status / topology<br/>view the fleet"]
    F --> G["aasm gateway stop"]

Two endpoints, one gateway. The gateway speaks gRPC on 127.0.0.1:50051 — this is what SDK shims and the sidecar proxy connect to. The operator commands aasm status, aasm agent, and aasm topology talk to the gateway’s HTTP API on http://localhost:8080. In the OSS alpha the gRPC listener is what aasm gateway start brings up; until an HTTP API server is also serving on 8080, the HTTP-backed commands report unreachable. That is expected and called out at each step below.

1. Start the gateway

Point the gateway at one of the bundled reference policies. policy-examples/ ships low-risk.yaml, medium-risk.yaml, and high-risk.yaml; low-risk allows and audits everything, which is the easiest starting point.

$ aasm gateway start --policy policy-examples/low-risk.yaml
Gateway started on grpc://127.0.0.1:50051  (pid 74472)
Logs: /Users/you/.aasm/logs/gateway.log

This spawns aa-gateway as a detached background process listening for gRPC on 127.0.0.1:50051. (If you built from source, ensure aa-gateway is reachable — aasm gateway start looks in $PATH, ~/.cargo/bin, and ./target/{debug,release}.)

Alternative — from a source checkout without installing: the gateway can be run directly with Cargo, which is the form the rest of the book uses:

cargo run -p aa-gateway -- --policy policy-examples/low-risk.yaml

It listens on the same 127.0.0.1:50051.

2. Confirm it is running

$ aasm gateway status
Gateway: running  pid=74472  listen=127.0.0.1:50051  uptime=5s

If nothing is running you get a non-zero exit and:

$ aasm gateway status
Gateway: not running

Tail the gateway log at any time with aasm gateway logs.

3. Check overall status

aasm status gives the fleet-wide picture — gateway health, registered agents, pending approvals, and budget. It queries the HTTP API at http://localhost:8080:

$ aasm status
Agent Assembly Status
─────────────────────────────────────
  Gateway:   http://localhost:8080
  Health:    ✗ unreachable
─────────────────────────────────────

RUNTIME HEALTH
──────────────
  API:         ✗ unreachable
  Uptime:      0s
  Connections: 0
  Lag:         0 ms

ACTIVE AGENTS
─────────────
  (no agents registered)

PENDING APPROVALS
─────────────────
  Count:  0

BUDGET STATUS
─────────────
  Daily spend : $-- (no limit set)
  Date:           --
  (no per-agent data)

Error: gateway is not running. Start it with: aasm start

The unreachable health here reflects the gRPC-vs-HTTP split described above: the gRPC gateway from step 1 is up, but the HTTP API on 8080 is not being served in this OSS-only setup. Once an API server is serving on 8080 (for example through the hosted control plane, or a future OSS API server), Health flips to reachable and registered agents appear in ACTIVE AGENTS.

Add --watch to auto-refresh the display every 5 seconds, or --json for a machine-readable header suitable for scripting and CI.

4. Observe an agent

Agents register with the gateway through an interception layer — they are not created from the CLI. Wire one of the SDKs into your agent, or front it with the sidecar proxy, and point it at the gateway:

• SDK shim (in-process): install python-sdk, node-sdk, or go-sdk and follow that SDK’s quickstart. The shim reports the calls it wraps to the gateway over gRPC.
• Sidecar proxy (no agent code changes): run aasm proxy start to intercept the agent’s outbound HTTPS and forward governance decisions to the gateway. The agent process must route through the proxy and trust its CA.
• eBPF (Linux only): kernel hooks observe OpenSSL TLS plaintext and exec/file syscalls. They report what the layers above missed; they do not block it.

A quick way to exercise the sidecar path end-to-end is the bundled Docker Compose stack, which runs aa-runtime as a sidecar against a stub agent:

cd examples/docker-compose
AA_API_KEY=dev-local-key docker compose up

The sidecar exposes the agent IPC socket at /tmp/aa-runtime-my-agent-001.sock and a readiness probe at http://localhost:8080/ready.

Once an agent is registered and the HTTP API is reachable, list the fleet:

aasm agent list          # all registered agents
aasm agent inspect <id>  # detail for one agent

Until then these commands report the API as unreachable:

$ aasm agent list
error: API request failed: error sending request for url (http://localhost:8080/api/v1/agents)

5. View the topology

aasm topology visualizes the agent fleet — trees, lineage, teams, and aggregate stats. Like aasm status, it reads the HTTP API:

aasm topology overview   # fleet-wide overview
aasm topology tree <id>  # subtree rooted at an agent
aasm topology stats      # aggregate statistics

With no reachable API it reports:

$ aasm topology overview
error: registry unreachable — check --api-url

6. Open a dashboard

For a live, interactive view there are two consoles:

• Web dashboard — aasm dashboard start serves the embedded SPA at http://127.0.0.1:3000 (port configurable; see Configuration). It blocks until Ctrl-C; use aasm dashboard open to launch your browser against an already-running server.
• Terminal (TUI) dashboard — aasm dashboard opens an interactive in-terminal dashboard for real-time monitoring, no browser required.

The web dashboard’s app shell looks like this after you sign in — the full governance navigation (Monitor / Control / Manage) down the left, with the approvals indicator, theme toggle, Settings, and Log out across the top:

The data panels are empty here because this is the open-source local-mode gateway, which serves the SPA but not the populated data API (that lives in the hosted control plane). See Observe in the dashboard for the full picture, including the live-operations and dark-mode views.

7. Stop the gateway

When you are done, shut the gateway down cleanly (SIGTERM, escalating to SIGKILL after the timeout):

aasm gateway stop

Where to go next

• CLI Reference — every aasm command and flag.
• Usage Guide — govern an agent end-to-end, author policies, and set budgets.
• Security Model — the threat model and the three-layer defense-in-depth rationale.

Last updated: 2026-08-06 by Chisanan232

CLI Reference — Overview

The aasm binary (crate aa-cli) is the operator front-end for Agent Assembly. It talks to a running aa-gateway over its HTTP / OpenAPI surface (default http://localhost:8080) for registry, policy, audit, approval, cost, and topology operations, and manages local daemon processes (gateway, proxy, dashboard) directly.

Invocation

aasm [OPTIONS] <COMMAND> [SUBCOMMAND] [ARGS]

Every command supports --help (-h for a one-line summary) at each layer:

aasm --help               # list all top-level commands
aasm policy --help        # list policy subcommands
aasm policy apply --help  # flags + arguments for one subcommand

Global options

These flags are defined on the root parser (aa-cli/src/lib.rs) and are global — they may be passed before the command or on any subcommand.

Authenticating. --api-key / AASM_API_KEY still work and are the right choice for CI and other non-interactive environments. For interactive use, prefer aasm login: it exchanges the key once for a short-lived scoped session (stored per context) so the raw key never sits on argv, in your shell history, or in the environment. See Authentication for the session model, expiry/auto-refresh, and the login / logout / whoami commands.

Several commands also expose a local --output or --json flag that overrides the global --output for that command only (e.g. aasm logs --output json, aasm status --json, aasm gateway status --json). These are called out on the relevant command pages.

Output formats

--output (source: aa-cli/src/output.rs) selects how list/get commands render:

• table (default) — human-readable, colorized tables via comfy-table.
• json — machine-readable pretty JSON.
• yaml — machine-readable YAML.

Commands that stream (aasm logs --follow, aasm approvals watch), visualize (aasm trace, aasm topology tree), or open a TUI (aasm dashboard) ignore --output where it does not apply.

Config and context resolution

CLI configuration lives at ~/.aa/config.yaml (source: aa-cli/src/config.rs). It holds named contexts (connection profiles), an optional default context, and dashboard settings:

default_context: production
contexts:
  production:
    api_url: https://api.example.com
    api_key: prod-key
  staging:
    api_url: https://staging.example.com
dashboard:
  port: 3000
  auto_open: false

The active API URL and key are resolved with this precedence (highest first):

1. Explicit --api-url / --api-key flags.
2. The named context — --context <name>, otherwise default_context.
3. Built-in default URL http://localhost:8080 (no key).

Manage contexts with the aasm context command group.

Sessions live separately from config. When you aasm login, the resulting scoped session is stored in ~/.aa/credentials.yaml (locked 0600), kept distinct from ~/.aa/config.yaml so that clearing a session (aasm logout) never rewrites your context definitions. See Authentication.

Note on paths. The CLI config file is ~/.aa/config.yaml. Separately, the locally-managed gateway uses ~/.aasm/ for its runtime artifacts — ~/.aasm/config.yaml (gateway config, see aasm start), ~/.aasm/policy.yaml, ~/.aasm/logs/gateway.log, and ~/.aasm/gateway.pid. These are distinct files.

Exit codes

aasm follows the standard convention:

• 0 — success.
• non-zero — failure. Common causes: the gateway is unreachable, the API returned a non-2xx status, a named context was not found, a file failed to parse, or a validation/simulation step found problems.

Some commands give the exit code a documented meaning so it can gate CI:

Command groups

Developer-only commands. Three command groups — aasm run (launch a governed AI dev tool), aasm tools (discover installed AI dev tools), and aasm integrations (the Developer Integration lifecycle — added to this set by AAASM-5309) — are gated behind the devtool region in aa-cli/src/commands/mod.rs and aa-cli/Cargo.toml.

Which channel you installed from decides whether you have them. .ci/strip-for-publish.sh removes that region in the publish-crates job of release.yml, so the strip applies to the crates.io publish and nothing else. cargo install aasm does not have the three commands. A source build (cargo build -p aa-cli), the GitHub Release tarballs, the curl installer and the Homebrew formula are all built from the unstripped tree in the build job, so those aasm binaries do have them — and their aa-runtime still carries the Developer Integration API bring-up.

aasm integrations is documented here because it is a shipped, user-facing surface on every channel except crates.io, and the omission was itself a documentation gap. aasm run and aasm tools remain undocumented in this reference. Where the strip does apply it is not cosmetic in the integrations case: a crates.io aa-runtime never binds the Developer Integration API socket, so the command would have nothing to connect to.

Last updated: 2026-08-04 by Chisanan232

Authentication (login / logout / whoami)

aasm authenticates to the gateway with an API key, but the key is a long-lived operator credential you do not want on every command line or in every CI environment variable. The auth workflow exchanges that key once for a short-lived, scoped JWT (the session) that the rest of the CLI presents on your behalf. This is the recommended way to authenticate: run aasm login once and subsequent commands authenticate without re-prompting.

The three commands on this page manage that session:

The session model

aasm login sends your API key to POST /api/v1/auth/token (source: aa-cli/src/auth/token.rs) and gets back { token, expires_at, scopes }. That scoped JWT — not the raw key — is what later commands attach as Authorization: Bearer <jwt>. The session is stored per context (source: aa-cli/src/auth/session.rs), so you can be logged into several gateways at once and each is managed independently.

Compared with putting the raw key on --api-key / AASM_API_KEY:

• The key never appears in argv, shell history, or process listings when you use the hidden prompt.
• The credential that travels on each request is short-lived (24h) and can be scope-narrowed (--scope read), limiting blast radius.

The raw-key path still works for non-interactive use — see Environment / flag fallback.

aasm login

Exchange an API key for a scoped session and store it for the active context.

Synopsis

aasm login [--scope <read|write|admin>]

Options

Plus the global options.

Where the key comes from — resolution precedence

login resolves the API key without ever placing it on argv (source: aa-cli/src/commands/login.rs), in this order:

1. The key already resolved into the active context — from --api-key, AASM_API_KEY, or the context’s stored api_key in ~/.aa/config.yaml (this is the global-options precedence).
2. Otherwise, a hidden interactive prompt (see below).

The hidden prompt

When no key is resolvable from the context, login prompts on stderr:

API key:

Input is read as a secure line (not echoed to the terminal), so the secret never lands in your shell history or on the command line. A blank entry is rejected rather than attempting an exchange with an empty credential.

What it stores, and where

On success the session is written to ~/.aa/credentials.yaml (source: aa-cli/src/auth/session.rs), a file kept separate from config.yaml so that logging out never rewrites your context definitions. On Unix the file is locked to 0600 and its directory to 0700, matching config.yaml. The stored session carries the JWT, its expiry, the granted scopes, and the source key it was minted from (retained for auto-refresh).

What it prints

A single confirmation line naming the context (its friendly name, or the URL for an unnamed context), the granted scopes, and a coarse expiry hint. It never prints the API key or the JWT.

Example

aasm login

API key:
Logged in to production (scopes: read, write; expires in 1d).

Request a read-only session:

aasm login --scope read

Logged in to production (scopes: read; expires in 1d).

Non-interactive (key supplied by the environment — no prompt appears):

AASM_API_KEY=aa_live_… aasm login --context staging

Errors

login exits non-zero (ExitCode::FAILURE) on any of these.

aasm logout

Clear the local session for the active context.

Synopsis

aasm logout

logout takes no arguments of its own — it acts on the active context selected by the global options (--context / --api-url).

Local-only — does not revoke the key

logout is local-only. It removes the session credential from ~/.aa/credentials.yaml on this machine, but it does not revoke the underlying API key server-side. The source key stays valid at the gateway, so a session minted from it on another machine keeps working. Revoking the key itself is a separate IAM operation (POST /iam/api-keys/{id}/revoke), deliberately kept distinct so logging out of one machine never invalidates a key in use elsewhere.

If a key is actually compromised, revoke it via IAM — logout alone is not enough.

Idempotent

Logging out of a context with no active session is a success, not an error, so scripts can call aasm logout unconditionally.

Examples

aasm logout

Logged out of context 'production'.

When there was nothing to clear:

No active session for 'production'.

aasm whoami

Show the active session for the current context — context name, gateway URL, scopes, expiry, and a truncated source-key hint.

Synopsis

aasm whoami [--output <table|json|yaml>]

Being not logged in is a normal state: whoami exits 0 either way, and prints guidance to run aasm login. It never prints the JWT or the full API key — every output format is built from a secret-free projection that carries only a short source_key_hint (source: aa-cli/src/commands/whoami.rs).

Options

Examples

Default table:

aasm whoami

Logged in
  context:    production
  api_url:    https://api.example.com
  scopes:     read, write
  expires_at: 1000000 (in 23h 41m)
  source_key: aa_live_su…

Not logged in:

aasm whoami

Not logged in (run 'aasm login').

JSON (for scripting):

aasm whoami --output json

{
  "logged_in": true,
  "context": "production",
  "api_url": "https://api.example.com",
  "scopes": [
    "read",
    "write"
  ],
  "expires_at": 1000000,
  "expires_in_secs": 1000,
  "expired": false,
  "source_key_hint": "aa_live_su…"
}

When not logged in, the machine-readable shape is simply { "logged_in": false }.

Expiry and auto-refresh

The scoped JWT has a 24-hour TTL and the server issues no refresh token (source: aa-cli/src/auth/token.rs). Instead, the CLI retains the source API key inside the session and silently re-exchanges it for a fresh JWT when the old one expires — this “auto-refresh” is transparent: you do not run any command for it (source: aa-cli/src/client.rs).

Re-exchange happens in two places:

1. Before a request, if the stored JWT is already past its expiry — the CLI re-mints from the source key and persists the fresh session.
2. On a 401 that slips past the pre-send check (clock skew, or a token revoked mid-flight then re-granted) — the CLI re-mints once and resends. A second consecutive 401 is treated as a genuine rejection, not retried further.

You must log in again only when the source key itself is revoked or rotated server-side: re-exchange then fails, and the CLI surfaces the not-logged-in error prompting you to run aasm login.

Environment and flag fallback

The raw-key path is fully supported and is the right choice for CI and other non-interactive environments where an interactive login is impractical:

• AASM_API_KEY — set the key in the environment.
• --api-key <KEY> — pass the key as a global flag.

When no stored session exists, the client attaches the raw key as the bearer directly (source: aa-cli/src/client.rs). Bearer resolution order is:

1. A stored session’s JWT (auto-refreshed on expiry).
2. Otherwise, --api-key / AASM_API_KEY (or the context’s stored key).
3. Otherwise, no Authorization header at all.

Use aasm login interactively; use AASM_API_KEY / --api-key in CI. In interactive use prefer login so the key never touches argv or the environment. The raw-key path avoids a persisted session on ephemeral CI runners.

The CLI does not fail-fast locally on a missing credential — the gateway is the sole authorization authority (a bypass-default gateway serves unauthenticated requests fine). The client sends what it has and lets the server rule.

Error messages you may see

Because the gateway is deny-by-default, an unauthenticated or under-scoped request is answered by the server, and the CLI translates the status into an actionable message (source: aa-cli/src/client.rs):

Security notes

• The API key and the JWT are never printed by any command — not by login’s confirmation line, not by whoami in any output format.
• When entered at the prompt, the key is never placed on argv; it is read as a hidden secure line and kept off your shell history.
• The credential store ~/.aa/credentials.yaml is locked to 0600 (directory 0700) on Unix, and is kept separate from config.yaml.
• A corrupt or partially-written credential file fails closed to “no session” rather than wedging the CLI.

See also

• CLI Overview — config and context resolution
• aasm context — manage the named contexts a session is keyed to.

Last updated: 2026-08-04 by Chisanan232

aasm status

Show fleet health, agents, approvals, and budget at a glance. aasm status fetches the deployment overview, runtime health, agent list, pending approvals, cost rollup, and storage health from the gateway in one shot and renders a dashboard-style summary.

Synopsis

aasm status [OPTIONS]

This command has no subcommands.

Options

Plus the global options.

Exit code

• 0 — all healthy.
• non-zero — the gateway is unreachable, at least one agent has violations, or the storage health probe reports unavailable. All failure modes collapse to a single non-zero code so shell scripts can gate on it.

Examples

Show the full status summary:

aasm status

Agent Assembly Status
─────────────────────────────────────
  Mode:      local
  Gateway:   http://localhost:7391
  Storage:   sqlite  (~/.aasm/local.db)
  Version:   0.0.1
  Uptime:    2h 15m 33s
  Health:    ✓ ok
─────────────────────────────────────

ACTIVE AGENTS
─────────────
┌──────────┬──────────────┬───────────┬───────────┬──────────┬──────────────────┬──────────────────┬───────┐
│ AGENT_ID │ NAME         │ STATUS    │ FRAMEWORK │ SESSIONS │ LAST_EVENT       │ VIOLATIONS_TODAY │ LAYER │
╞══════════╪══════════════╪═══════════╪═══════════╪══════════╪══════════════════╪══════════════════╪═══════╡
│ a1b2c3d4 │ research-bot │ ● Running │ langgraph │ 3        │ 2m ago tool_call │ 0                │ sdk   │
└──────────┴──────────────┴───────────┴───────────┴──────────┴──────────────────┴──────────────────┴───────┘

PENDING APPROVALS
─────────────────
  Count:  1
  Oldest: 2m ago

BUDGET STATUS
─────────────
  Daily spend : $12.50 / $50.00  █████░░░░░░░░░░░░░░░  25%
  Date:           2026-04-30
  (no per-agent data)

Continuously refresh:

aasm status --watch

Machine-readable deployment header for CI:

aasm status --json

{
  "mode": "local",
  "gateway_url": "http://localhost:7391",
  "storage_backend": "sqlite",
  "storage_path": "~/.aasm/local.db",
  "version": "0.0.1",
  "uptime_secs": 8133,
  "health": "ok"
}

Full snapshot as JSON (every section):

aasm status --output json

Last updated: 2026-07-19 by Bryant

aasm agent

Manage monitored agent processes registered with the gateway.

Synopsis

aasm agent <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options. list, inspect, suspend, and resume honor --output table|json|yaml; kill ignores --output and always prints a plain-text confirmation.

aasm agent list

List all registered agents, with optional client-side filters.

Options

Example

aasm agent list --status Active --framework langgraph

AGENT_ID   NAME           FRAMEWORK   VERSION   STATUS   PID     SESSIONS   LAST_EVENT
a1b2c3…    research-bot   langgraph   1.2.0     Active   48213   3          2026-06-09T14:02:11Z

Columns that the server did not supply render as - (e.g. PID, SESSIONS, LAST_EVENT for an agent with no live process or events).

aasm agent inspect

Render a detailed view of a single agent as a two-column Field | Value table (identity, status, tools, PID, sessions, last event, policy violations, and metadata when present), followed by separate tables for active sessions, recent events, and recent traces when the agent has any.

Arguments

Example

aasm agent inspect a1b2c3d4e5f600112233445566778899

┌───────────────────┬──────────────────────────────────┐
│ Field             ┆ Value                            │
╞═══════════════════╪══════════════════════════════════╡
│ ID                ┆ a1b2c3d4e5f600112233445566778899 │
│ Name              ┆ research-bot                     │
│ Framework         ┆ langgraph                        │
│ Version           ┆ 1.2.0                            │
│ Status            ┆ Active                           │
│ Tools             ┆ search, fetch, summarize         │
│ PID               ┆ 48213                            │
│ Sessions          ┆ 3                                │
│ Last Event        ┆ 2026-06-09T14:02:11Z             │
│ Policy Violations ┆ 0                                │
└───────────────────┴──────────────────────────────────┘

Recent Traces:
┌────────────┬──────────────────────┐
│ SESSION_ID ┆ TIMESTAMP            │
╞════════════╪══════════════════════╡
│ 7f3a…      ┆ 2026-06-09T14:02:11Z │
└────────────┴──────────────────────┘
Tip: run `aasm trace <session-id>` to visualize a trace

Framework and Version are separate rows. When the agent has metadata, active sessions, or recent events, those render as their own rows/tables above the traces section.

aasm agent suspend

Suspend a running agent. The reason is logged for audit.

Arguments / options

Example

aasm agent suspend a1b2c3… --reason "investigating cost spike" --force

Agent a1b2c3… suspended.
  Previous status: Active
  New status:      Suspended(Manual)

aasm agent resume

Resume a previously suspended agent.

Arguments

Example

aasm agent resume a1b2c3…

Agent a1b2c3… resumed.
  Previous status: Suspended(Manual)
  New status:      Active

aasm agent kill

Deregister and terminate an agent.

Arguments / options

Example

aasm agent kill a1b2c3… --force

Agent a1b2c3… has been killed.

Last updated: 2026-07-19 by Chisanan232

aasm policy

Manage governance policies — apply new versions, inspect history, roll back, diff, simulate, validate locally, and view effective policy.

Synopsis

aasm policy <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options.

aasm policy apply

Apply a policy YAML file and save it to version history.

aasm policy apply ./policies/prod.yaml --applied-by alice@example.com

Policy applied successfully.
  Version:    9f2c1a
  Timestamp:  2026-06-09T14:00:00Z
  Active:     true
  Rules:      12

aasm policy history

List recent policy versions.

aasm policy history -n 5

aasm policy rollback

Roll back to a previous policy version, making it active again.

aasm policy rollback 9f2c1a

aasm policy diff

Show a colorized unified diff between two policy versions. Colors are suppressed when stdout is not a TTY.

aasm policy diff 9f2c1a 7ab310

aasm policy simulate

Simulate a policy against historical audit events or live traffic without enforcing it. Exits non-zero if the simulation detects any violation, so it can gate a CI pipeline.

aasm policy simulate --policy ./candidate.yaml --against ./audit/session.jsonl

Simulation Report
--------------------------------------------------
Total events:       412
Allowed:            409
Denied:             3
Approval required:  0
Budget impact:      $0.00

EVENT#   ACTION               DECISION     REASON
----------------------------------------------------------------------
0        file_write           deny         block-system-paths

The command exits non-zero when the report has any denied or errored outcome (so it can gate CI). The EVENT# table is printed only when there are flagged outcomes, and the Budget impact line only when a budget impact is computed.

aasm policy validate

Validate a policy YAML file locally (no apply, no gateway contact). Exits 0 when valid, 1 with error details on stderr otherwise.

aasm policy validate ./policies/prod.yaml

Policy is valid: ./policies/prod.yaml

aasm policy get

Show the currently active policy YAML, or a specific version.

aasm policy get --version 9f2c1a

aasm policy list

List all policies deployed to the governance runtime. Takes no flags of its own (uses the global --output).

aasm policy list --output json

NAME      STATUS     UPDATED_AT               RULES
9f2c1a    Active     2026-06-09T14:00:00Z     12
7ab310    Inactive   2026-06-01T09:30:00Z     11

aasm policy show

Show an agent’s effective policy view. By default prints the agent identity; add a flag to expand into the capability cascade or budget rollup.

aasm policy show a1b2c3… --show-permissions

Capability        Effective   Granted by      Denied by
search            Allow       team:research   —
file_write        Deny        —               org

Last updated: 2026-07-19 by Bryant

aasm topology

Visualize agent topology — fleet overview, delegation trees, teams, ancestry lineage, and aggregate statistics.

Synopsis

aasm topology <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options, including --output table|json|yaml. Only tree renders as a box-drawing tree; overview, team, lineage, and stats render as tables in the default table mode.

aasm topology overview

Show a fleet-wide topology overview across all teams and root agents.

aasm topology overview --status active

aasm topology tree

Render a delegation subtree rooted at one agent, using box-drawing characters.

aasm topology tree a1b2c3… --max-depth 3

Each node prints as <name> [<status>] <<team_id>> (the <team_id> segment is shown only when the agent has a team). Agent IDs are not printed in tree mode — use --output json if you need them.

└── research-bot [active] <research>
    ├── fetch-worker [active] <research>
    │   └── parse-worker [active] <research>
    └── summarize-worker [active] <research>

aasm topology team

Show all agents belonging to a single team.

aasm topology team research --status active

aasm topology lineage

Show an agent’s complete ancestry chain, ordered root-first. In table mode the lineage renders as a flat table with columns DEPTH | AGENT_ID | NAME | TEAM | DELEGATION_REASON, followed by a (this is a root agent) note when the agent has no ancestors above it.

aasm topology lineage 778899… --show-permissions

Agent: 778899…  |  Ancestors: 3

┌───────┬──────────┬──────────────┬──────────┬───────────────────┐
│ DEPTH ┆ AGENT_ID ┆ NAME         ┆ TEAM     ┆ DELEGATION_REASON │
╞═══════╪══════════╪══════════════╪══════════╪═══════════════════╡
│ 0     ┆ a1b2c3…  ┆ root-bot     ┆ research ┆ -                 │
│ 1     ┆ d4e5f6…  ┆ fetch-worker ┆ research ┆ fetch upstream    │
│ 2     ┆ 778899…  ┆ parse-worker ┆ research ┆ parse response    │
└───────┴──────────┴──────────────┴──────────┴───────────────────┘

aasm topology stats

Show aggregate topology statistics — total/root/active/suspended/deregistered counts, max depth, teams, orphans, and average children per parent. Takes no flags of its own (uses the global --output). In table mode each metric is its own row.

aasm topology stats --output json

┌─────────────────────┬───────┐
│ METRIC              ┆ VALUE │
╞═════════════════════╪═══════╡
│ Total agents        ┆ 42    │
│ Root agents         ┆ 5     │
│ Max depth           ┆ 4     │
│ Active              ┆ 38    │
│ Suspended           ┆ 3     │
│ Deregistered        ┆ 1     │
│ Teams               ┆ 5     │
│ Orphans             ┆ 0     │
│ Avg children/parent ┆ 2.31  │
└─────────────────────┴───────┘

When present, a Depth histogram (DEPTH | COUNT) and a Team-size histogram (TEAM_SIZE | COUNT) are printed as additional tables below the summary.

Last updated: 2026-07-19 by Bryant

aasm alerts

Manage governance alerts — list, inspect, and resolve.

Synopsis

aasm alerts <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options.

aasm alerts list

List governance alerts as a color-coded table, with optional filters.

aasm alerts list --severity critical

ID       SEVERITY   CATEGORY          STATUS       MESSAGE
al-301   critical   budget            unresolved   team:research over daily cap
al-298   warning    policy_violation  unresolved   file_write denied (agent a1b2c3…)

aasm alerts get

Render a detailed key-value view of one alert.

aasm alerts get al-301

aasm alerts resolve

Resolve an alert, optionally attaching a note.

aasm alerts resolve al-301 --reason "raised team cap" --force

Alert al-301 resolved.

Last updated: 2026-07-19 by Bryant

aasm approvals

Manage human-in-the-loop approval requests — list pending actions, approve or reject them, and watch for new requests in real time.

Synopsis

aasm approvals <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options.

aasm approvals list

List approval requests as a colored table. The TIMEOUT_IN column is color-coded (red < 60s, yellow 60–180s, green > 180s).

aasm approvals list --status pending

ID        AGENT      ACTION        CONDITION       SUBMITTED_AT          TIMEOUT_IN
ap-77     a1b2c3…    file_write    /etc/hosts      2026-06-09T14:01:00Z  2m 30s

aasm approvals get

Show details of a single pending approval request.

aasm approvals get ap-77

aasm approvals approve

Approve a pending action.

aasm approvals approve ap-77 --reason "verified safe"

Approved: ap-77 (status: approved)

aasm approvals reject

Reject a pending action. A reason is required in non-interactive mode (supply --reason or pipe it on stdin).

aasm approvals reject ap-77 --reason "writes outside allowed path"

Rejected: ap-77 (status: rejected)

aasm approvals watch

Watch for new approval requests in real time over the gateway WebSocket events endpoint (filtered to approval events).

aasm approvals watch --interactive

  aasm approvals watch (interactive)
  [a] approve  [r] reject  [Up/Down] navigate  [q] quit

  > ap-78  a1b2c3…             network_egress                 3m 00s

The interactive view marks the selected row with > and prints id agent action countdown per row — it does not show a condition field. (The non-interactive stream prints NEW <id> | agent=… | action=… | condition=… lines instead.)

Last updated: 2026-07-19 by Bryant

aasm audit

Query audit log entries and export tamper-evident compliance reports.

Synopsis

aasm audit <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options.

Time filters. --since accepts a duration shorthand (30m, 2h, 1d) or an ISO 8601 timestamp; --until accepts an ISO 8601 timestamp.

aasm audit list

Query audit log entries from the gateway (GET /api/v1/logs) with optional filters, rendered as a table (or --output json|yaml). The result column is color-coded: allow=green, deny=red, pending=yellow.

aasm audit list --result deny --since 2h --limit 20

TIMESTAMP             AGENT     ACTION            TOOL         RESULT   POLICY
2026-06-09T14:01:00Z  a1b2c3…   PolicyViolation   file_write   deny     block-system-paths

aasm audit export

Export audit entries fetched from the gateway to CSV/JSON/JSONL, with optional compliance metadata headers. Writes to stdout unless --output-file is given.

aasm audit export --format jsonl --compliance soc2 --since 1d \
  --output-file audit-2026-06-09.jsonl

aasm audit verify-chain

Verify the SHA-256 hash chain of a local JSONL audit log file. Exits non-zero if the chain is broken (tamper evidence).

aasm audit verify-chain ./audit/session-7f3a.jsonl

OK — 412 entries verified

aasm audit compliance-export

Full-fidelity compliance export of a local JSONL audit file. Preserves the SHA-256 hash chain anchors, credential findings (kind + offset only — never the raw secret), and delegation lineage for SIEM ingestion and regulatory review.

aasm audit compliance-export --input ./audit/session-7f3a.jsonl \
  --format jsonl --compliance eu-ai-act --output-file compliance.jsonl

Last updated: 2026-07-19 by Bryant

aasm logs

Query and stream audit-log events. In default mode it fetches recent entries over HTTP; with --follow it streams events live over the gateway WebSocket (like tail -f).

Synopsis

aasm logs [OPTIONS]

This command has no subcommands.

Options

Plus the global options.

Examples

Show the last 50 entries:

aasm logs

2026-06-09T14:01:00Z [VIOLATION] a1b2c3…  file_write denied: /etc/passwd
2026-06-09T14:01:05Z [APPROVAL]  a1b2c3…  network_egress pending: api.openai.com

Filter to violations and budget events for one agent:

aasm logs --agent a1b2c3… --type violation,budget --since 1h

Stream live (Ctrl-C to stop):

aasm logs --follow --type violation

Emit JSON for piping into jq:

aasm logs --output json --limit 200 | jq '.[].message'

Last updated: 2026-06-11 by Chisanan232

aasm trace

Visualize a single agent session trace as an indented tree or a horizontal timeline. The trace is fetched from the gateway and the flat span list is folded into a hierarchy (LLM calls, tool calls, tool results, policy allow/deny).

Synopsis

aasm trace [OPTIONS] <SESSION_ID>

This command has no subcommands.

Arguments

Options

Plus the global options.

Examples

Tree view (default):

aasm trace 7f3a1c2b

Trace: 7f3a1c2b
├─ ●  LLM gpt-4  1200ms
│  ├─ ●  TOOL search  340ms
│  │  └─ ←  RESULT search  12ms
│  └─ ❌ DENY file_write  0ms  (path outside allowlist)
└─ ●  LLM gpt-4  800ms

Each event line is <icon> <label> <duration>, where the icon encodes the event kind (● LLM, ● TOOL, ← RESULT, ✅ ALLOW, ❌ DENY). Policy denials still carry a duration and are printed in red with the violation reason appended in parentheses.

Timeline view:

aasm trace 7f3a1c2b --format timeline

The timeline flattens every event (including nested ones) into one row each, prefixed with a Timeline: <session_id> header. Each row is a fixed-width uppercase kind tag and label, an ASCII bar sized relative to the longest event, and the duration:

Timeline: 7f3a1c2b
LLM    gpt-4                ████████████████████████████████████████  1200ms
TOOL   search              ███████████                                340ms
RESULT search              █                                          12ms
DENY   file_write                                                     0ms
LLM    gpt-4               ███████████████████████████                800ms

Last updated: 2026-07-19 by Bryant

aasm cost

Query cost summary and forecast spending.

Synopsis

aasm cost <SUBCOMMAND> [OPTIONS]

Both subcommands accept the global options.

aasm cost summary

Show the cost summary for a time period, optionally grouped by a dimension.

aasm cost summary --period month --group-by agent

AGENT_ID   DAILY_SPEND   MONTHLY_SPEND
a1b2c3…    $6.00         $180.10
d4e5f6…    $4.41         $132.30

COST SUMMARY (Monthly)
──────────────────
  Monthly spend: $312.40
  Budget limit:  $1,000.00
  Utilization:   31.2%
  Date:          2026-06

With --group-by agent, the per-agent table (always three columns: AGENT_ID, DAILY_SPEND, MONTHLY_SPEND) prints first, followed by the global summary. The spend and limit labels read Daily for --period today and Monthly for --period month.

aasm cost forecast

Forecast monthly spending by extrapolating the current daily rate over the remaining days of the month. Takes no flags of its own (uses the global --output).

aasm cost forecast

COST FORECAST
─────────────
  Date:              2026-06-09
  Day of month:      9/30
  Current daily:     $12.50
  Projected monthly: $375.00
  Monthly limit:     $1,000.00
  Projected util:    37.5%

Last updated: 2026-07-19 by Bryant

aasm dashboard

Real-time governance monitoring. With no subcommand, aasm dashboard opens an interactive terminal (TUI) dashboard. The subcommands manage an embedded single-page-app (SPA) web server instead.

Synopsis

aasm dashboard [SUBCOMMAND] [OPTIONS]

The TUI streams status over HTTP polling plus a WebSocket event feed. Panels: fleet health + agents, event log, budget bars, and the pending-approvals queue with countdown timers. Keyboard shortcuts (Tab/Shift-Tab to cycle panels, arrows to select, a/r to approve/reject, p policy viewer, ? help, q quit).

The dashboard port resolves from (highest first): AASM_DASHBOARD_PORT env var → --port flag → dashboard.port in ~/.aa/config.yaml (default 3000).

aasm dashboard start

Serve the embedded SPA at http://127.0.0.1:<port>. Blocks until Ctrl-C. Reverse-proxies /api/* to the configured gateway.

Exposure caution. The dashboard is designed for local / self-hosted / operator-controlled use and binds loopback by default. Do not put it directly on the public internet without a trusted authenticating layer (VPN, private network, or an authenticated reverse proxy) in front. Browser session auth uses sessionStorage + CSP (an accepted OSS trade-off, not hardened against same-origin XSS), and WebSocket streams authenticate with short-lived single-use tickets so no credential rides the URL. See SECURITY.md and ADR 0012.

aasm dashboard start --port 8088 --open

Dashboard running at http://127.0.0.1:8088
Press Ctrl-C to stop.

Once the server is up, the browser opens to the dashboard home / overview — your confirmation that the dashboard is set up and running:

Navigating to the Live Operations route lays out the L1→L2→L3 traffic pipeline, a tail -f event stream with filters, and the approval queue:

Captured against the open-source local-mode gateway, which serves the SPA but not the live event/approval data API (that is the hosted control plane), so the stream shows “reconnecting…” and the pipeline columns are empty. The chrome and layout are fully real. See Observe in the dashboard for more.

aasm dashboard open

Open the system browser to an already-running dashboard server.

aasm dashboard open --port 8088

aasm dashboard stop

Stop a dashboard server previously started with aasm dashboard start. Takes no flags.

aasm dashboard stop

Dashboard stopped.

Last updated: 2026-07-23 by Bryant

aasm gateway

Manage the aa-gateway governance daemon directly — the process that holds the agent registry, evaluates the policy engine, and writes the audit log.

aasm gateway start runs the gateway with low-level flags (listen address, socket, policy path). For the higher-level local developer workflow (deployment mode + dashboard), see aasm start.

Synopsis

aasm gateway <SUBCOMMAND> [OPTIONS]

aasm gateway start

Spawn aa-gateway in the background (or foreground with --no-detach). The binary is resolved in priority order (highest first): alongside the aasm executable itself (a sibling aa-gateway), then $PATH, then ~/.cargo/bin, then ./target/release, then ./target/debug.

aasm gateway start --listen 127.0.0.1:50051 --policy ./policy.yaml

aasm gateway stop

Terminate a running gateway gracefully (SIGTERM, escalating to SIGKILL). Takes no flags.

aasm gateway stop

aasm gateway status

Report whether aa-gateway is running and serving gRPC.

aasm gateway status --json

{
  "running": true,
  "pid": 48213,
  "listen": "127.0.0.1:50051",
  "uptime_seconds": 8133
}

aasm gateway logs

Tail the gateway log file, with optional level filtering. Non-JSON lines pass through so operator notes are preserved.

aasm gateway logs --follow --level warn

Last updated: 2026-07-19 by Bryant

aasm proxy

Manage the aa-proxy sidecar — its lifecycle, the per-host CA trust, and log tailing. The proxy intercepts outbound HTTPS via MitM so network-egress policy can be enforced without code changes (layer 2 of the three-layer model).

Synopsis

aasm proxy <SUBCOMMAND> [OPTIONS]

aasm proxy start

Spawn aa-proxy in the background (or foreground with --no-detach). The binary is resolved from $PATH, then ~/.cargo/bin — trusted, absolute locations only. A cwd-relative ./target/release fallback was deliberately removed as a security fix (AAASM-4020): resolving relative to the current working directory would let whoever controls where aasm runs substitute an attacker-planted aa-proxy.

aasm proxy start --listen 127.0.0.1:8899 --gateway http://localhost:50051

The listen address must be loopback, and must name its port

--listen is checked before anything is spawned and before a state file is written, so a refused start leaves nothing behind (AAASM-5348). Two addresses that used to start a proxy no longer do:

• A non-loopback address — 0.0.0.0, a LAN address, [::]. The proxy reads intercepted traffic under a CA this machine trusts and injects your provider credentials into forwarded requests, so anything that can reach the listener can do both.
• Port 0 — it asks the OS for any free port, but the recorded endpoint would still say 0. The proxy would bind a real port that nothing can name: aasm run refuses a port-0 endpoint, aasm proxy stop could not reach the process, and the start would report failure while the proxy kept running.

Both previously succeeded and produced an endpoint aasm run would then refuse to route a governed tool at — a proxy that worked for everything except the one job it exists to do. aasm proxy start and aasm run now apply the same test, so an address one accepts is an address the other trusts.

--allow-remote-clients states intent, and still refuses

Intent is not authorization. A proxy reachable from other hosts also needs TLS on its listener and client authentication — aa-proxy implements neither, so the flag currently changes only which refusal you get:

$ aasm proxy start --listen 0.0.0.0:8899 --allow-remote-clients
error: refusing to listen on 0.0.0.0:8899: --allow-remote-clients was given, but
a proxy reachable from other hosts also requires protection aa-proxy does not
implement: TLS on the proxy listener, client authentication and authorization.
Being reachable is not being trusted — without those, every host that can route
to 0.0.0.0:8899 is an authorized client of an interception endpoint that holds
CA material and provider credentials. Listen on a loopback address instead.

The flag exists rather than being omitted because a refusal that names the two missing protections is more useful than one that says only “not supported”, and because the guard relaxes on its own once either protection is implemented. To reach another machine’s proxy today, forward the loopback port over SSH.

AA_PROXY_ADDR is not covered by this check. The guard lives in aasm proxy start; running the aa-proxy binary directly with a non-loopback AA_PROXY_ADDR — which is what the container image and the self-hosting example do — still binds it. Tracked as AAASM-5370.

aasm proxy stop

Stop the running proxy sidecar. Takes no flags.

aasm proxy stop

aasm proxy status

Show whether the proxy sidecar is running (confirmed via a TCP connect probe).

aasm proxy status --json

aasm proxy install-ca

Install the proxy CA certificate into the OS trust store so intercepted TLS connections validate.

aasm proxy install-ca --yes

aasm proxy uninstall-ca

Remove the proxy CA certificate from the OS trust store. Same options as install-ca.

aasm proxy uninstall-ca --yes

aasm proxy logs

Tail the proxy log file, with optional level/time filtering.

aasm proxy logs --follow --level warn --since 10m

Last updated: 2026-08-02 by Chisanan232

aasm integrations

Install, verify, repair and remove Developer Integrations for AI dev tools — the governance wiring that makes a tool like Claude Code run through Agent Assembly instead of straight out to its provider.

Absent from cargo install aasm — and only from there. aasm integrations is a developer-only command group. Like aasm run and aasm tools, it is gated behind the devtool region in aa-cli/src/commands/mod.rs and aa-cli/Cargo.toml, and .ci/strip-for-publish.sh removes that region in the publish-crates job of release.yml — the crates.io publish and nothing else. A source build (cargo build -p aa-cli), the GitHub Release tarballs, the curl installer and the Homebrew formula are all built from the unstripped tree, so they do carry this command. Where the strip does apply it is not cosmetic: a crates.io aa-runtime never binds the DI-API socket this command talks to, so the surface would have nothing to connect to.

This page is the command reference — subcommands, flags, defaults, exit codes. For what the lifecycle means (profiles, evidence, protection levels, what is and is not measured), read aasm integrations in the Developer Integrations section and Protection levels.

What it is, in one paragraph

aasm integrations is a client of the Developer Integration API and nothing more. It holds no per-tool knowledge, performs no mutation of its own, and never derives a protection state locally: every per-tool fact arrives over one Unix socket from an adapter inside the trusted aa-runtime, and every mutation happens there. That is why the command needs a running runtime — there is no in-process fallback, by design (ADR 0030 §7.1).

Invocation

aasm integrations [OPTIONS] <COMMAND> [ARGS]

<TOOL> is the tool id as aasm integrations list reports it — claude-code, codex, github-copilot, windsurf-cascade.

These same ids are accepted by aasm run, which has its own shorter canonical spellings (claude, codex, copilot, windsurf). An id copied out of aasm integrations list launches the tool it names; the two commands do not have separate vocabularies.

Only claude-code has a lifecycle today. The other three are carried by LegacyAdapterShim: they detect and report, but install and repair are refused with exit 3 because their plan steps name no destination file. That refusal is deliberate — a success that performed nothing would be worse. Being listed means the tool is recognised, not that it can be integrated; see Limitations.

Options common to every subcommand

The global options (--context, --output, --api-url, --api-key) apply, plus one flag defined on the group itself:

--no-autostart

Lifecycle commands need a running Agent Assembly runtime. By default aasm starts one, says so on stderr, and waits:

$ aasm integrations list
Starting Agent Assembly runtime…

A missing socket is a bootstrap action, not a transient error — it is never silently retried. Pass --no-autostart in CI, where leaving a daemon behind is worse than failing; the missing runtime then becomes exit code 7 (runtime_unavailable) instead.

--output json

--output json (and --output yaml) emit the same model the human table is rendered from, so anything readable is parseable. Reports go to stdout; notices, prompts and errors go to stderr, so aasm integrations status claude-code --output json | jq stays valid even when the runtime had to be started first.

Machine-readable output also makes the mutating commands non-interactive: there is nothing on the other end that can answer a prompt, so install, repair and remove abort (exit 9) rather than block, unless --yes is passed.

aasm integrations list

aasm integrations list [OPTIONS]

aasm integrations plan <TOOL>

Mutates nothing. Prints the material changes an install would make, the permissions it would need, and the mechanisms the tool cannot use with the reason.

The --profile tokens are what you type; the wire tokens the DI-API receives are recommended, strict and observe_only. observe-only computes and audits every decision and applies none of them, and is never displayed as protection — status says monitoring.

Why --scope managed alone is refused

--scope managed reads like a third choice next to user and project, and it says nothing about administrator authorization. On its own it is therefore rejected with exit 9 (aborted) and a remediation naming the flag that does mean consent:

$ aasm integrations plan claude-code --scope managed
error: nothing was changed: writing the administrator-managed settings surface needs an explicit opt-in

--install-managed-settings is that opt-in. It selects the managed surface, carries the privileged-step consent, and asks for administrator authorization for one file write — the settings surface the tool documents as non-overridable. It is the only route to Host Enforced, it is off by default, and the default install stays fully unprivileged.

Before you are asked to approve anything, the plan states the exact path, the exact content and its SHA-256, the diff against what is on the host, any conflict, and the backup and rollback behaviour. An unavailable or denied authorization is a truthful failure, never a quieter install; a non-interactive run fails immediately rather than waiting for credentials.

Host Enforced means the policy is installed where you cannot rewrite it. It does not mean a bypass was demonstrated to fail — see Limitations. The procedure that would close that gap is Measuring managed-settings enforcement.

aasm integrations install <TOOL>

Takes every plan flag above, plus:

The preview you approve is the same plan object that gets applied — not a second rendering of it — so you cannot consent to something you were not shown. Silence is not consent: without a terminal and without --yes, the command aborts and changes nothing.

aasm integrations status <TOOL>

No flags beyond the common ones. Reports the achieved protection level and the observation that justifies it, split by how the observation was obtained (exercised vs read-back vs could-not-be-checked), including the rungs this host cannot reach. The timestamp is part of the claim: a status says “verified at T”, not “true now”.

Gateway Protected is reported only on adjudicated exercised evidence. Configuration that reads back correctly justifies at most Integrated.

aasm integrations verify <TOOL>

No flags beyond the common ones. Runs the adjudicated protection exercise and exits 0 only when the protected path was actually exercised and the outcome was protective. Otherwise it exits 6 — read that as “not measured”, never as “measured and failed”. The probe uses a synthetic secret chosen by the adapter and run by the service; no real credential is read, sent or printed.

aasm integrations repair <TOOL>

Repairing nothing is a success and exits 0 — see Outcome: did the world change? below, which is what tells a restored integration from one that never needed restoring. nothing_to_repair additionally says which no-op it was: no receipt accounts for the tool at all, or the AASM-owned state already matches the receipt it has.

aasm integrations remove <TOOL>

Removal is derived from the receipt, not re-derived from current host state: it undoes what was done, not what would be done now. Anything that cannot be undone automatically is printed as a residual action first, every time; --force only answers “yes, remove anyway and leave those behind” and never removes anything the plan did not name.

Restoration is semantics-exact, not byte-exact — the keys Agent Assembly owns are removed and the prior values restored, but formatting and key order in a file someone else also writes are not guaranteed to be reproduced verbatim.

Removing an integration that is already gone is a success and exits 0, so a teardown loop does not have to special-case its second run. What tells the two runs apart is the outcome below.

Outcome: did the world change?

The exit code answers did the command succeed?. It does not answer did the world change?, and the two are different questions: a remove of an integration that is already absent succeeded and modified nothing. Overloading one code with both is how aasm integrations repair X && echo repaired came to print “repaired” for a tool that was never installed.

So no exit code was minted for a no-op. A legitimate no-op is a successful idempotent outcome and exits 0, and the mutation question is answered by a separate, explicitly reported outcome:

changed and unchanged are reported on the result’s first line and as outcome in --output json / --output yaml. refused and failed are named on stderr, beside the specific exit code from the table below — stdout stays empty on a non-zero exit, so a QA harness has no result to record from a run that refused.

Branching on it

This is wrong, and is the defect this contract exists to prevent:

# WRONG — prints "repaired" for a tool that was never installed.
aasm integrations repair claude-code --yes && echo repaired

This is right:

case $(aasm integrations repair claude-code --yes --output json | jq -r .outcome) in
  changed)   echo 'drifted state was restored' ;;
  unchanged) echo 'nothing needed repairing' ;;
esac

Which commands report it

A --dry-run reports null rather than a token. It changed nothing, but it also did not establish that the end state already holds — the drift it is previewing is proof of the opposite. The one exception is a --dry-run against a tool with no integration at all: that state is settled before any plan is previewed, so it reports unchanged.

install does not report it yet. The runtime knows whether an apply mutated anything — the engine computes it — but the DI-API’s ApplyView does not carry the fact, and this client will not infer it from a receipt timestamp: a wrong unchanged tells a script the world did not change when it did, which is worse than no answer. Until the wire carries it, compare aasm integrations status before and after. Tracked on AAASM-5499.

Exit codes

aasm integrations gives every outcome its own code so a wrapper can branch on the code rather than parse English out of stderr. The table below is generated from aa-cli/src/commands/integrations/exit.rs and printed by aasm integrations --help.

These answer did the command succeed? only. For did the world change? see Outcome above — a no-op exits 0 here and is distinguished there, never by a code of its own.

2 is deliberately unused. clap exits 2 for a usage error, so reusing it would make “you typed the command wrong” indistinguishable from a real outcome.

aasm integrations verify claude-code || case $? in
  6) echo 'protection not measured — treat as unprotected, do not report a failed block' ;;
  5) aasm integrations repair claude-code --yes ;;
esac

10 and 11 — which build answered

These two are about the runtime that served the command, not about the tool it was asked about. A reachable socket is not evidence that the right thing answered: a runtime built from another checkout, or one whose executable has been deleted, answers perfectly well and describes its host. That is how a healthy Claude Code once got reported as not_installed.

Every aasm integrations command therefore checks which build answered, before producing any output.

Which commands emit which:

Read-only commands still answer under an unverifiable standing because refusing them would make the situation undiagnosable — they are exactly the commands you use to find out which runtime answered and stop the wrong one. They say so on stderr, and --output json carries the standing so a recorded result stays marked:

"runtime": {
  "provenance": {
    "standing": "unverifiable",   // verified | unverifiable | refuted
    "verdict": "unverifiable",    // the specific fact behind the standing
    "build_sha": "unknown",
    "build_id_source": "absent",  // injected | checkout | packaged | absent
    "pid": 24601,
    "fields": [                   // which facts were absent, matched, mismatched
      { "field": "build_sha", "status": "absent", "expected": "unknown", "reported": "unknown" }
    ],
    "reachable_runtimes": 1
  }
}

unverifiable is never reported as verified, on any surface or in JSON. Branch on standing, not on the presence of a build_sha.

reachable_runtimes is one-directional evidence. Above one it proves ambiguity — each of those sockets was connected to, so each of those runtimes exists, and the result cannot be attributed to one of them. Equal to one it proves only that nothing else was found: the scan probes files named devint*.sock, in the answering socket’s own directory, once as the session opens. A runtime under another name, in another directory (which AA_DEVINT_SOCKET makes trivial), or started a moment later is not counted. Read 1 as “no duplicate was observed”, never as “this is the only runtime”.

standing is the one field that folds in every reason a result may not be attributable, which is why it is the only one a wrapper needs to read. verdict is narrower — it reports the identity comparison alone, and two runtimes compiled from one commit have identical identities, so verdict reads verified for both of them. standing cannot read verified while reachable_runtimes is above one.

A wrapper that records evidence should refuse anything but verified:

aasm integrations status claude-code --output json > result.json || case $? in
  10) echo 'the wrong runtime answered — stop it and re-run'; exit 1 ;;
  11) echo 'the runtime carries no build identity'; exit 1 ;;
esac
jq -e '.runtime.provenance.standing == "verified"' result.json \
  || { echo 'result is not attributable to this build'; exit 1; }

--allow-unverified-runtime downgrades both refusals to a stderr warning for a deliberately mixed installation. It does not change what is reported: the standing reaches --output json and rides above the result in the table rendering, so a result obtained through it stays marked as unverified rather than passing as verified.

It also disarms the multiplicity refusal, which is not an identity cause at all. With more than one runtime reachable the command answers from whichever one it connected to and the others are never consulted; reachable_runtimes says how many there were, and standing cannot read verified while that is above one.

Environment

See Configuration → Environment variables for the full table and the file modes these paths are held to.

See also

• aasm integrations — the lifecycle explained
• Onboarding a Developer Integration — the same journey as a walkthrough, with troubleshooting.
• Protection levels
• Limitations and known bypasses
• Developer Integration API

Last updated: 2026-08-07 by Chisanan232

aasm start / aasm stop

Start and stop the locally-managed Agent Assembly gateway. These are the high-level developer-laptop commands: aasm start picks a deployment mode, binds the right address, runs the gateway in the background, and (in local mode) enables the dashboard. aasm stop terminates it gracefully and cleans up the PID file.

For low-level gateway control (explicit listen address, Unix socket, policy path), see aasm gateway.

aasm start

Synopsis

aasm start [OPTIONS]

Options

Exposure caution. --mode remote binds 0.0.0.0, putting the API and the operator dashboard on the network. The dashboard is designed for local / self-hosted / operator-controlled use — do not expose it directly to the public internet without a trusted authenticating layer (VPN, private network, or an authenticated reverse proxy) in front. See SECURITY.md and ADR 0012.

Behavior

1. Resolve the listen address from mode + port.
2. Exit early (idempotent) if a gateway is already running at that address — verified by a live PID file and a successful TCP probe.
3. Spawn the entrypoint binary for the selected mode (background, or foreground with --foreground): local mode launches aa-api-server (which serves the dashboard SPA and the full /api/v1/* REST surface from a single process); remote mode launches aa-gateway via --listen.
4. In background mode, write the PID file and wait for the listener before printing the success banner.

Exit 0 on a normal start, an idempotent “already running” path, or a clean foreground exit. Exit non-zero if the readiness probe times out or the spawn fails.

Example

aasm start --mode local --port 7391

✓ Agent Assembly gateway started
  Mode:    local
  Address: http://localhost:7391
  PID:     48213

aasm stop

Synopsis

aasm stop [OPTIONS]

Options

Behavior

Resolves the PID file (~/.aasm/gateway.pid) and chooses one of four terminal states — no PID file, stale PID file, graceful SIGTERM, or escalated SIGKILL — always cleaning up the PID file so the next aasm start sees a clean slate.

Example

aasm stop --timeout 15

Gateway stopped (PID 48213).

Last updated: 2026-07-23 by Bryant

aasm sandbox

Run a WebAssembly tool inside the Agent Assembly tool-execution sandbox, with filesystem, CPU (instruction fuel), memory, and wall-clock isolation. This surfaces the aa-sandbox runtime to the CLI without going through the cloud /dispatch_tool HTTP route.

Synopsis

aasm sandbox <SUBCOMMAND> [OPTIONS]

aasm sandbox run

Run a WebAssembly module under WASI preview 1 inside a fresh sandbox and report the outcome. Unset limits fall back to the safe-by-default values.

aasm sandbox run ./tool.wasm --fuel 50000000 --wall-clock-ms 10000

sandbox exited cleanly (exit_code=0)

On success the command prints a single line with the module’s exit code. If the sandbox refuses or traps the module (fuel exhaustion, memory-cap or wall-clock overrun, or a WASI trap), it instead writes sandbox refused or trapped the module: <reason> to stderr and exits non-zero. Fuel and wall-time usage are not tracked or reported.

aasm sandbox info

Show the default sandbox runtime limits. Takes no arguments.

aasm sandbox info

aasm sandbox — WASI preview 1 tool-execution sandbox
  fuel (instructions):      10000000
  memory ceiling:           16 pages (1024 KiB)
  wall-clock deadline (ms): 5000
  preopened dirs:           (none — fully sealed FS)

Last updated: 2026-07-19 by Bryant

aasm config

Validate and boot an agent-assembly.toml runtime configuration file. These operate on the runtime TOML (storage drivers, etc.) — distinct from the CLI’s own ~/.aa/config.yaml connection profiles (see aasm context).

Synopsis

aasm config <SUBCOMMAND>

aasm config validate

Parse the TOML file and resolve every [storage] driver name against the built-in driver registry. Exits 0 when valid; 1 with the error on stderr otherwise. Unknown sections are ignored.

aasm config validate ./agent-assembly.toml

✓ agent-assembly.toml valid — storage driver: memory

aasm config boot

Resolve every [storage] driver through the registry, build each backend, and perform a sample policy lookup to confirm the configuration actually boots. Exits 0 on success; 1 with the error on stderr.

aasm config boot ./agent-assembly.toml

✓ booted storage backends; sample policy lookup OK

Last updated: 2026-06-11 by Chisanan232

aasm context

Manage named API contexts (connection profiles) stored in ~/.aa/config.yaml. A context bundles an API URL and optional API key under a name so you can switch between gateways with --context <name>.

See Config and context resolution for how the active context is resolved.

Synopsis

aasm context <SUBCOMMAND> [OPTIONS]

aasm context list

List all configured contexts with their API URLs. Takes no arguments.

aasm context list

production *  https://api.example.com (key set)
staging  https://staging.example.com

One line per context — no header row. A * marker follows the default context’s name, and (key set) follows the URL when an API key is stored for that context. When no contexts are configured, aasm context list prints No contexts configured. Use \aasm context set` to add one.` instead.

aasm context set

Create or update a named context.

AASM_API_KEY env var. When --api-key is omitted, aasm context set reads the key from the AASM_API_KEY environment variable (an empty value is treated as unset). Passing --api-key on the command line prints a warning and is discouraged, because argv is world-readable via ps, /proc/<pid>/cmdline, and shell history, which leaks the operator bearer token. The global --api-key flag honors the same AASM_API_KEY env var.

AASM_API_KEY=staging-key aasm context set staging --api-url https://staging.example.com

Context 'staging' saved.

aasm context use

Switch the default context (the one used when --context is not passed).

aasm context use production

Switched to context 'production'.

Last updated: 2026-07-19 by Chisanan232

aasm admin

Gateway administrative operations. The current scope is manual retention; more admin subcommands are added as the operator surface grows.

Synopsis

aasm admin <SUBCOMMAND> [OPTIONS]

The subcommand accepts the global options, honoring --output yaml (defaults to pretty JSON).

aasm admin run-retention

Trigger one manual retention pass (POST /api/v1/admin/retention-policy/run). Exits 0 on a successful pass, non-zero when the gateway is unreachable or returns a non-2xx status (the error chain is printed to stderr).

aasm admin run-retention --dry-run

{
  "ran_at": "2026-06-09T14:05:00Z",
  "hot_rows": 14293,
  "compressed_rows": 512,
  "archived_rows": 128,
  "dropped_rows": 0,
  "freed_bytes": 0,
  "dry_run": true
}

Last updated: 2026-07-19 by Bryant

aasm uninstall

Uninstall Agent Assembly tools installed via the curl installer.

aasm uninstall is a thin wrapper over the installer’s uninstall engine. The curl installer (scripts/install-cli.sh) is the single source of truth for the manifest-driven removal and --purge logic; on install it persists a runnable copy at ${AASM_STATE_DIR:-~/.aasm}/aasm-uninstall, and this command forwards to it so the CLI, the curl installer, and the offline fallback all share one engine. Homebrew-managed installs are detected by the engine and redirected to brew uninstall.

If no local uninstaller is found, the command prints the Homebrew and curl fallbacks and exits non-zero.

Synopsis

aasm uninstall [OPTIONS]

Safe by default: without --purge, only the installed components are removed; Agent Assembly-owned local data (config + state) is left in place.

aasm uninstall --dry-run
aasm uninstall --purge --yes

Last updated: 2026-07-19 by Bryant

aasm version

Show CLI and gateway version information. Prints the aasm CLI version, then probes the gateway health endpoint (GET /api/v1/health) for the gateway and API versions. When the gateway is unreachable, the gateway/api rows show an unreachable marker.

Synopsis

aasm version

This command has no subcommands or flags of its own. It honors the global --output and the resolved API context (--api-url / --context).

aasm -V / aasm --version prints only the CLI version (the standard clap flag). aasm version additionally reports the gateway and API versions.

Example

aasm version

COMPONENT   VERSION
cli         0.0.1-rc.6
gateway     0.0.1-rc.6
api         0.0.1-rc.6

JSON form:

aasm version --output json

Last updated: 2026-07-19 by Bryant

aasm completion

Generate a shell completion script for aasm and write it to stdout. Source or install the output to get tab-completion for commands, subcommands, and flags.

Synopsis

aasm completion <SHELL>

This command has no subcommands.

Arguments

Examples

Bash (current session):

source <(aasm completion bash)

Zsh (install into a completions directory on $fpath):

aasm completion zsh > ~/.zfunc/_aasm

Fish:

aasm completion fish > ~/.config/fish/completions/aasm.fish

Last updated: 2026-06-11 by Chisanan232

Usage Guide

This guide walks through the real, day-to-day tasks an operator performs with Agent Assembly, using the aasm CLI, the governance gateway, the three interception layers, and the dashboard. Every command and every screenshot on these pages was produced against the actual 0.0.1-beta.4 build — where a scenario needs a platform Agent Assembly does not target locally (for example the Linux-only eBPF layer, or the SaaS control-plane API the web dashboard talks to), the page says so explicitly rather than showing a mock-up.

What you can do

The shape of every scenario

Agent Assembly governance always has the same three moving parts:

1. A gateway — the brain. It holds the agent registry, evaluates policy, tracks budgets, and writes the audit log. You start it once.
2. At least one interception layer — the SDK shim, the aa-proxy sidecar, or the eBPF kernel hooks — that observes what an agent does and asks the gateway for an allow/deny decision.
3. A policy — a YAML document describing what is allowed: capabilities, network egress, per-tool rules, budgets, and approval gates.

The operator surface for all of this is the aasm binary:

aasm — command-line tool for Agent Assembly

Commands:
  admin       Gateway administrative operations
  agent       Manage monitored agent processes
  alerts      Manage governance alerts
  audit       Query audit log entries and export compliance reports
  logs        Query and stream audit log events
  policy      Manage governance policies
  context     Manage named API contexts (connection profiles)
  config      Validate an `agent-assembly.toml` runtime configuration file
  completion  Generate shell completion scripts
  status      Show fleet health, agents, approvals, and budget at a glance
  version     Show CLI and gateway version information
  trace       Visualize a session trace (tree or timeline)
  approvals   Manage human-in-the-loop approval requests
  cost        Query cost summary and forecast spending
  dashboard   Open an interactive TUI dashboard for real-time governance monitoring
  gateway     Manage the aa-gateway governance daemon
  sandbox     Run a WebAssembly tool inside the Agent Assembly sandbox
  topology    Visualize agent topology, trees, lineage, and statistics
  proxy       Manage the aa-proxy sidecar — lifecycle, CA trust, and log tailing
  start       Start the locally-managed Agent Assembly gateway process
  stop        Stop the locally-managed Agent Assembly gateway process

Two global flags appear in nearly every example below:

• --api-url <URL> — where the CLI sends its requests. Defaults to the SaaS control-plane API on http://localhost:8080. When you run the local gateway (aasm start / aa-gateway --mode local) it serves its HTTP API on http://127.0.0.1:7391, so the local-mode examples pass --api-url http://127.0.0.1:7391.
• --output <table|json|yaml> — table for humans, json/yaml for scripting.

A note on ports. The gRPC policy server listens on 127.0.0.1:50051 (where SDKs and the proxy connect). The local control-plane HTTP API and the embedded dashboard are served on 127.0.0.1:7391. The full web dashboard’s data API (/api/v1/fleet, /api/v1/policies, …) is provided by the SaaS/cloud control plane on port 8080, which is not part of the open-source local runtime — see Observe in the dashboard for what renders locally and what needs the hosted backend.

Last updated: 2026-06-24 by Bryant

Govern an agent end-to-end

Goal. Take a real AI dev tool on your machine — Claude Code, Codex, Copilot, or Windsurf — and launch it so that everything it does runs through Agent Assembly governance: it is registered with the gateway, tagged to a team and trace, and routed through the proxy so its tool-calls and network requests are policy-checked and audited.

This guide does not work on a crates.io aasm. aasm tools and aasm run are developer-only commands: .ci/strip-for-publish.sh removes them in release.yml’s publish-crates job, so they are absent from cargo install aasm and present everywhere else — a source build, the GitHub Release tarballs, the curl installer and the Homebrew formula. See CLI overview → developer-only commands.

There is a newer path for dev tools. The lifecycle described here — detect, wire up, launch — has been superseded for AI dev tools by aasm integrations, which adds plan, receipt, verify, drift/repair and remove, and reports an evidence-backed protection level instead of a static governance tier. aasm integrations is stripped on crates.io too. This guide is retained because aasm run is still how a governed session is launched.

Prerequisites

• The aasm binary built (cargo build -p aa-cli; the binary is at ./target/debug/aasm).
• The gateway binary on PATH for the aasm start helper (cargo build -p aa-gateway --bin aa-gateway).
• At least one supported AI dev tool installed.

Step 1 — See which tools Agent Assembly can govern

aasm discovers the AI dev tools already installed on the system and reports the governance level it can apply to each. This is a real probe of the machine, not a static list:

$ aasm tools list
+---------------+---------+---------------------------------------------------------+------------------+
| TOOL          | VERSION | PATH                                                    | GOVERNANCE LEVEL |
+======================================================================================================+
| ClaudeCode    | 2.1.220 | /opt/homebrew/bin/claude                                | L2Enforce        |
|---------------+---------+---------------------------------------------------------+------------------|
| Codex         | 0.144.6 | /opt/homebrew/bin/codex                                 | L2Enforce        |
|---------------+---------+---------------------------------------------------------+------------------|
| GitHubCopilot | 1.388.0 | /Users/you/.vscode/extensions/github.copilot-1.388.0    | L2Enforce        |
+---------------+---------+---------------------------------------------------------+------------------+

The governance level is each adapter’s static, self-declared ceiling — what it says it could achieve for that tool, not what is currently in force. L2Enforce is the highest level any shipped adapter declares; L3Native is defined in the L0–L3 matrix but no adapter returns it today, and aa-devtool-saas is the only one capped at L1Observe.

A level here is not a protection claim. It is a declaration, not evidence: nothing about this column says traffic was inspected. For an evidence-backed answer to “is this tool actually protected right now, and how do you know”, use aasm integrations status <tool>, which reports the protection ladder derived from observations rather than a self-declared tier.

Step 2 — Start the gateway

The gateway is the decision engine every governed action is checked against. For a local, in-process control plane:

$ aasm start --mode local --port 7391

This serves the HTTP control-plane API and the dashboard on http://127.0.0.1:7391 with a local SQLite store. You can confirm it is up:

$ aasm --api-url http://127.0.0.1:7391 status
Agent Assembly Status
─────────────────────────────────────
  Mode:      local
  Gateway:   http://127.0.0.1:7391
  Storage:   sqlite
  Version:   0.0.1-beta.4
  Uptime:    2m 24s
  Health:    ✓ ok
─────────────────────────────────────

STORAGE
───────
  Backend:     sqlite
  Path:        /Users/you/.aasm/local.db
  DB Health:   ✓ ok  (0ms)
  Rows:        audit_events: 0 hot
               agents: 0  |  policies: 0

The fleet starts empty (agents: 0) — nothing is governed until you launch a tool under aasm run in the next step.

Step 3 — Write the policy the session runs under

Note the policies: 0 in the status above. A running gateway is a decision engine with nothing to decide from, and aasm run refuses to launch a tool in that state: an absent policy is not permission. Write one first.

$ cat > ~/.aasm/policy.yaml << 'EOF'
apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: research-team
spec:
  tools:
    "*":
      allow: false
    read_file:
      allow: true
  network:
    allowlist:
      - api.anthropic.com
EOF
$ aasm policy validate ~/.aasm/policy.yaml
Policy is valid: /Users/you/.aasm/policy.yaml

~/.aasm/policy.yaml is one of the locations aasm run searches, along with --policy <FILE> and $AA_POLICY — the same order aasm gateway start uses. The full order and the four states a resolution can land in (two of which refuse) are in Policy YAML Reference → Where a governed launch finds this file.

Applying a policy to the gateway is a different action. aasm policy apply uploads a document to the gateway’s version history; it writes nothing to the locations aasm run searches. Run both if you want the same document in both places — a policy can be live on the gateway and still leave the next aasm run unconfigured.

Step 4 — Launch the tool under governance

aasm run <tool> is the heart of this scenario. It assigns the session an agent identity, a team, and a trace id for lineage tracking, wires in the proxy, and then execs the real tool. Before running it for real, use --dry-run to see exactly what governance wiring will be applied — nothing is launched:

$ aasm run claude --team-id research --agent-id research-bot-01 --dry-run
policy=enforced — 2 rule(s) from /Users/you/.aasm/policy.yaml
--- aasm run dry-run ---
agent_id:    research-bot-01
trace_id:    dry-run-daa9d73a-f2fc-4977-9d00-50f4c4025fa9
session_id:  dry-run-0d7a0c16-25b2-456b-84e8-b7907fa963d1

--- policy ---
state:  enforced
source: /Users/you/.aasm/policy.yaml
detail: enforced — 2 rule(s) from /Users/you/.aasm/policy.yaml

--- managed settings ---
<dry-run: managed settings not generated>

--- launch command ---
claude

--- environment ---
AA_AGENT_ID=research-bot-01
AA_REGISTRATION_ID=dry-run-2b00ef56-3f35-4ef9-8164-ea899dfe90aa
AA_SESSION_ID=dry-run-0d7a0c16-25b2-456b-84e8-b7907fa963d1
AA_TEAM_ID=research
AA_TRACE_ID=dry-run-daa9d73a-f2fc-4977-9d00-50f4c4025fa9
AI_AGENT=claude-code_2-1-165_agent
CLAUDECODE=1
CLICKUP_API_TOKEN=***MASKED***
GITHUB_TOKEN=***MASKED***
JIRA_API_TOKEN=***MASKED***
SLACK_BOT_TOKEN=***MASKED***
...

Notice three things that are doing real work:

• The --- policy --- receipt names which of the four effective-policy states this launch resolved to, and from which file. It is printed for all four, including the two that refuse: a preview whose whole job is to say what a live run would do has to show you state: unconfigured rather than omit the section and let “no policy at all” look like a formatting quirk. On a state that would refuse, the preview warns and still completes.
• The AA_* environment variables (AA_AGENT_ID, AA_TEAM_ID, AA_TRACE_ID, AA_REGISTRATION_ID, AA_SESSION_ID) are injected so the launched tool’s events carry identity and lineage back to the gateway.
• Secret-looking environment variables in your shell — API tokens, PATs — are masked (***MASKED***) in the launch environment that gets logged, so credentials never leak into the audit trail.

When you drop --dry-run, the same wiring is applied for real and the tool starts. Useful flags:

The --enforcement-mode distinction matters when rolling governance out: start with --observe to see what would be blocked without breaking the agent, then switch to enforce once the policy is right. Neither mode waives the policy requirement: --observe chooses what happens to a decision, and an unconfigured launch has nothing to decide from, so it is refused either way.

Step 5 — Observe the governed agent

Once the tool is running under aasm run, the registered agent appears in the fleet and its actions flow into the audit log. You inspect it with:

$ aasm agent list                 # all registered agents
$ aasm agent inspect <agent-id>   # one agent in detail
$ aasm topology team research     # the whole team
$ aasm status                     # fleet health at a glance

and watch its decisions live via the dashboard — see Observe in the dashboard.

Result

You now have a real AI tool running with a stable governed identity, its tool-calls and outbound requests routed to the gateway for an allow/deny decision, secrets scrubbed from the recorded environment, and an audit trail keyed to the agent, team, and trace you assigned in Step 4.

Routing is not proof. Everything above describes configuration that was applied, which is not evidence that anything inspected the traffic — and a tool started directly, outside aasm run, inherits none of this wiring. To turn “configured” into a measured claim, use the integration lifecycle: aasm integrations verify <tool> runs an adjudicated exercise on the model-bound path and exits 0 only when the protected path was actually exercised and the outcome was protective. Its limitations page states what remains unmeasured.

Last updated: 2026-08-01 by Chisanan232

Enforce an egress policy

Goal. Restrict the hosts an agent is allowed to reach, so a prompt-injected or confused agent cannot exfiltrate data to an arbitrary endpoint. You author a network allowlist, dry-run it against recorded traffic before applying it, and then enforce it at the proxy layer.

How egress enforcement works

Network egress is the job of the sidecar proxy (aa-proxy), the second of the three interception layers. It terminates outbound HTTPS with a per-host CA (MitM) and, for every CONNECT, asks: is this host on the policy’s allowlist? Hosts that fail the check are refused before any bytes leave the machine — no code change in the agent required.

The allowlist lives in the network section of a policy:

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: egress-allowlist
  version: "1.0.0"
spec:
  network:
    allowlist:
      - api.openai.com
      - "*.githubusercontent.com"

Allowlist matching semantics

The proxy matches each requested host against every allowlist entry using these rules (from aa_core::policy::is_host_allowed_by_egress_allowlist):

The leftmost-label wildcard (*.example.com) requires at least one extra label to the left and anchors on the right, so it cannot be fooled by an attacker-crafted host like example.com.evil.net.

Step 1 — Validate the policy locally

Validation parses and type-checks the YAML without contacting a gateway, and warns about unrecognised keys so you catch typos early:

$ aasm policy validate egress-policy.yaml
Policy is valid: egress-policy.yaml

Step 2 — Dry-run against recorded traffic

aasm policy simulate replays an audit-log JSONL file through the policy engine and reports what each event would have decided — without enforcing anything. This is how you prove a new allowlist before it can break production traffic.

A replay file is one JSON object per line; each line is an audit event whose payload is the serialized governance action. For egress, the action is a NetworkRequest:

{"event_type":"ToolCallIntercepted","agent_id":"researcher-1","payload":"{\"NetworkRequest\":{\"url\":\"https://api.openai.com/v1/chat/completions\",\"method\":\"POST\"}}"}
{"event_type":"ToolCallIntercepted","agent_id":"researcher-1","payload":"{\"NetworkRequest\":{\"url\":\"https://evil.example.com/exfil\",\"method\":\"POST\"}}"}
{"event_type":"ToolCallIntercepted","agent_id":"researcher-1","payload":"{\"NetworkRequest\":{\"url\":\"https://raw.githubusercontent.com/org/repo/main/README.md\",\"method\":\"GET\"}}"}

Run the simulation:

$ aasm policy simulate --policy egress-policy.yaml --against traffic.jsonl
Simulation Report
--------------------------------------------------
Total events:       3
Allowed:            1
Denied:             2
Approval required:  0

EVENT#   ACTION               DECISION     REASON
----------------------------------------------------------------------
1        net:POST:https://evil.example.com/exfil deny         host not in network allowlist
2        net:GET:https://raw.githubusercontent.com/org/repo/main/README.md deny         host not in network allowlist

The report lists the flagged (non-allow) outcomes. api.openai.com (event 0) was allowed and so does not appear in the flagged list; the exfiltration attempt to evil.example.com was denied, as expected.

Honest caveat — two matchers, one allowlist. The raw.githubusercontent.com request was denied by the simulator above even though *.githubusercontent.com is on the allowlist. That is because the policy simulate decision path matches the host with an exact string comparison, whereas the live aa-proxy CONNECT path uses the glob-aware matcher described in the table above (which would allow it). When validating wildcard egress rules, confirm the live proxy behaviour as well as the simulation; treat a simulation deny on a wildcard host as “verify against the proxy”, not necessarily a real block.

For scripting and CI gating, write the structured report to a file and key off the exit status:

$ aasm policy simulate --policy egress-policy.yaml --against traffic.jsonl \
    --output-file report.json
$ cat report.json
{
  "total_events": 3,
  "denied": 2,
  "allowed": 1,
  "approval_required": 0,
  "budget_impact_usd": null,
  "flagged_outcomes": [
    { "event_index": 1, "action": "net:POST:https://evil.example.com/exfil",
      "decision": "deny", "reason": "host not in network allowlist" },
    { "event_index": 2, "action": "net:GET:https://raw.githubusercontent.com/org/repo/main/README.md",
      "decision": "deny", "reason": "host not in network allowlist" }
  ]
}

You can also dry-run against live traffic for a fixed window instead of a file:

$ aasm policy simulate --policy egress-policy.yaml --live --duration 60s

Step 3 — Enforce at the proxy

Bring up the sidecar and trust its CA so TLS interception works:

$ sudo aasm proxy install-ca     # add the local root CA to the OS trust store
$ aasm proxy start               # listens on 127.0.0.1:8899 by default
$ aasm proxy status

aasm proxy start accepts --listen <addr> (default 127.0.0.1:8899), --gateway <url> to point it at the gateway that owns the policy, and --ca-dir <dir> for CA storage. Agents launched via aasm run (absent from cargo install aasm, present on every other channel) have the proxy injected automatically (Step 3 of Govern an agent end-to-end); for other processes, route their HTTPS through the proxy address.

When the policy is applied, the proxy refuses any CONNECT to a host outside the allowlist and the refusal is written to the audit log.

Result

Outbound traffic is now constrained to an explicit allowlist, verified with a dry-run before it could affect a running agent, and enforced at the network layer without modifying the agent’s code.

Last updated: 2026-08-06 by Chisanan232

Team budgets and cost

Goal. Put a hard spend cap on what an agent (and a team) can burn on model calls, so a runaway planning loop cannot run up an unbounded bill — and watch spend accumulate against that cap.

How budgets work

The gateway tracks per-agent and per-team spend and evaluates it on every governed model call. Budgets are declared in the budget section of a policy. These are the real fields the gateway parses:

apiVersion: agent-assembly/v1
kind: Policy
metadata:
  name: research-budget
  version: "1.0.0"
spec:
  budget:
    daily_limit_usd: 25.0          # per-agent cap, resets each day
    monthly_limit_usd: 400.0       # per-agent cap, resets each month
    org_daily_limit_usd: 100.0     # organisation-wide daily cap
    org_monthly_limit_usd: 2000.0  # organisation-wide monthly cap
    timezone: "Asia/Taipei"        # IANA tz for the reset boundary (default UTC)
    action_on_exceed: deny         # "deny" (default) or "suspend"
    window: "1h"                   # optional sub-day rollover window (humantime)

Step 1 — Validate and apply the budget policy

$ aasm policy validate research-budget.yaml
Policy is valid: research-budget.yaml

$ aasm policy apply research-budget.yaml --applied-by alice@example.com

policy apply saves the policy to version history (see aasm policy history / aasm policy rollback), so a budget change is auditable and reversible.

Step 2 — Watch spend against the cap

aasm cost summary reports spend for the current period. By default it shows today; pass --period month for the month, and --group-by agent to break it down per agent:

$ aasm cost summary --period today
$ aasm cost summary --period month --group-by agent

Each command takes --output json|yaml for scripting.

To see where spend is heading, aasm cost forecast projects the month from the current daily rate:

$ aasm cost forecast

The fleet-level aasm status view also surfaces a budget block at a glance:

BUDGET STATUS
─────────────
  Daily spend : $-- (no limit set)
  Date:           --
  (no per-agent data)

(The example above is from a fresh gateway with no budget applied and no spend yet — once a budget policy is applied and agents start spending, the daily spend and per-agent rows populate.)

Step 3 — See budgets in topology

aasm topology team <team-id> lists every agent in a team; add --show-budget to include each agent’s governance/budget posture in the tree:

$ aasm topology team research --show-budget

What happens at the cap

When an agent reaches its daily_limit_usd (or the org cap), the gateway applies action_on_exceed:

• deny — the offending model call is denied and audited. The agent keeps running but cannot spend until the window resets.
• suspend — the agent is suspended (you can later aasm agent resume <id>).

Either way the decision lands in the audit log, so cost overruns are accountable after the fact, not just blocked in the moment.

Result

The team now has enforceable per-agent and organisation-wide spend caps with a defined reset boundary and a clear over-budget action, plus CLI views to track actual spend and forecast the month.

Last updated: 2026-06-11 by Bryant

Observe in the dashboard

Goal. Watch the governed fleet in real time. Agent Assembly ships two observation surfaces from the same aasm binary: a web dashboard (a Vite/React SPA) and an in-terminal TUI. This page shows what each looks like and how to bring it up.

The web dashboard

The dashboard is a single-page React app. In production it is embedded into the gateway and served at /; for UI development it runs under Vite on port 3000 and proxies /api to the control-plane API on port 8080.

Bring it up locally

The local-mode gateway serves the compiled SPA on its HTTP port (7391 by default). Build the dashboard bundle once, then start the gateway pointed at it:

$ cd dashboard && pnpm install && pnpm build      # produces dashboard/dist/
$ cd .. && aasm start --mode local --port 7391
# the dashboard is now at http://127.0.0.1:7391/

The login screen

The dashboard authenticates with an API key. This screen renders entirely client-side, so it is the same whether or not a backend is reachable:

The app shell and navigation

After authenticating, the canonical 12-route navigation appears, grouped into Monitor (Overview, Fleet, Topology, Live Ops, Alerts, Audit Log), Control (Capability, Policy, Secret Scrubbing), and Manage (Cost & Budget, Agent Groups, Members & Access). The header carries the approvals indicator, a light/dark theme toggle, Settings, and Log out:

An implemented page — Policies

The Policies page is the visual policy builder. It shows All / Active / Proposed tabs and a + new policy action; opening a row drops into the editor:

More implemented routes — Live Ops and Topology

The Live Operations route renders the real-time governance layout: the L1→L2→L3 traffic pipeline (Identity → Capability → Scrub → External), a tail -f event stream with agent/team/op-type/status filters and an auto-scroll toggle, and the approval queue. Against the local-mode gateway the event stream shows “reconnecting…” (no backend feed) and the columns are empty, but the full operator layout is real:

The Topology route lists agents and teams; here it honestly reports 0 agents · 0 teams because the fleet data API is not part of the local runtime:

Light and dark themes

The header theme toggle flips the entire token-driven UI between light and dark. Here is the Overview route in dark mode:

Honest caveat — what renders locally vs. what needs the hosted backend. The screenshots above are all real captures of the 0.0.1-beta.4 SPA served by the local-mode gateway. The data panels are empty (zero policies, zero agents, “not implemented yet” on some routes) because the dashboard’s data API — /api/v1/fleet, /api/v1/policies, /api/v1/capability/matrix, and the auth-token endpoint — is provided by the SaaS/cloud control plane on port 8080, which is not part of the open-source local runtime. The local-mode gateway on 7391 serves the SPA and a small set of endpoints (/healthz, /api/v1/admin/status), so the chrome, navigation, theming, and page shells are fully real while the populated tables require the hosted backend. Routes still marked “not implemented yet” (e.g. Overview) render a ComingSoon placeholder by design in this build.

The terminal TUI

For operators who live in a terminal, aasm dashboard (no subcommand) launches an interactive full-screen TUI built on ratatui, with a live feed and keyboard-driven approval handling:

$ aasm dashboard
# ...full-screen TUI; press 'q' to quit

Open an interactive TUI dashboard for real-time governance monitoring

Usage: aasm dashboard [OPTIONS] [COMMAND]

Commands:
  start  Serve the embedded SPA at http://127.0.0.1:<port>. Blocks until Ctrl-C
  open   Open the browser to an already-running dashboard
  stop   Stop a dashboard server started with `aasm dashboard start`

The TUI polls the control-plane REST API and subscribes to a WebSocket feed for live events; selecting a pending approval lets you approve or reject it inline (y / n).

Honest caveat — no live TUI screenshot here. The TUI requires an interactive terminal (it switches to the alternate screen and raw mode) and a reachable events/approvals API (port 8080) to display populated panels. Driven headlessly against the empty local backend it renders the frame but with no data to show, so a meaningful still capture is not reproducible in this environment — the launch command and --help above are real, and the panels populate once the hosted control plane (or a backend with live agents) is connected.

Serving the SPA without a browser launch helper

aasm dashboard start serves the embedded SPA directly and blocks until Ctrl-C; aasm dashboard open opens your browser to an already-running server, and aasm dashboard stop stops a server started with start. Pass --port (or set AASM_DASHBOARD_PORT) to choose the port, and --open to launch the browser once it is ready.

Result

You can observe the fleet either in the browser (rich, point-and-click) or in the terminal (fast, keyboard-driven), both from the same binary and both backed by the same gateway.

Last updated: 2026-06-24 by Bryant

Choosing interception layers

Goal. Decide which of the three interception layers to deploy, and how to combine them, for a given governance requirement. Agent Assembly enforces policy through three independently-deployable layers; this page is about the practical trade-offs, with the real commands for each.

The three layers at a glance

Listed lowest-latency-cost first, highest-detection-authority first:

The gateway is the common brain for all three — every layer asks the same policy engine for its decision and writes to the same audit log.

When to use each

• Reach for the SDK layer when you control the agent’s code and want the lowest-overhead, most precise instrumentation — it sees tool-call arguments and results directly, in process.
• Add the proxy when you cannot or do not want to modify the agent, and the risk you care about is network egress / data exfiltration. It is the most practical way to govern a third-party or closed-source tool. See Enforce an egress policy.
• Add eBPF when you need visibility into what an agent does outside the paths the other layers cover — e.g. it shells out, writes files, or makes raw connections that skip both the SDK and the proxy. It raises the chance of detecting such a bypass; it is a detection backstop, not a catch-all, and it does not block.

Combining layers

The layers are additive, not exclusive. A typical governed deployment runs the SDK and the proxy: the SDK gives rich, in-process tool-call governance, while the proxy backstops the network path for anything the SDK does not see and that is routed through it. On Linux, eBPF sits underneath both as an observation floor — it widens what you can detect, not what you can prevent.

For what remains uncovered even with all three deployed, see Limitations and known bypasses.

aasm run reports a governance level per tool (see Govern an agent end-to-end), but read it for what it is: a static, self-declared ceiling on how deeply an adapter could integrate — no in-tree adapter declares L3Native today, and every local dev-tool adapter declares L2Enforce. It is not a measurement and not a protection claim.

For what is actually protecting a given tool right now, and the evidence behind it, use aasm integrations status <tool>, which reports the derived protection ladder. (aasm run and aasm integrations are stripped from the crates.io publish only — a source build, the GitHub Release tarballs, the curl installer and the Homebrew formula all carry them.)

Layer 2 in practice — the proxy

$ sudo aasm proxy install-ca # trust the local root CA so TLS interception works
$ aasm proxy start           # background sidecar on 127.0.0.1:8899
$ aasm proxy status          # confirm it is running
$ aasm proxy logs            # tail the proxy log
$ aasm proxy uninstall-ca    # remove the CA when you are done

aasm proxy start takes --listen <addr> (default 127.0.0.1:8899), --gateway <url>, and --ca-dir <dir>.

Layer 3 in practice — eBPF

The eBPF layer is Linux-only: its uprobes/kprobes/tracepoints attach to a running kernel.

$ aasm proxy status
not running

On macOS the eBPF userspace crate compiles with non-Linux stubs (the KprobeManager/UprobeManager attach paths are #[cfg(target_os = "linux")]), so it builds for development but does not attach probes. To exercise the real kernel hooks — SSL-library uprobes for outbound TLS, exec/openat/unlink kprobes, and the sched_process_exec tracepoint — run on Linux.

Honest caveat. This page does not show live eBPF probe output because the attaching code is gated to Linux and this build was exercised on macOS. The architecture (userspace aa-ebpf loading compiled aa-ebpf-probes and reading a shared BPF ring buffer) is real and documented in the crate; the live capture requires a Linux host with the privileges to load eBPF programs.

Result

You can match the interception layer (or stack of layers) to the requirement: SDK for precision where you own the code, proxy for egress control without touching agent code, eBPF for kernel-level detection of what escaped both on Linux — all feeding one gateway and one audit log.

Match the requirement to what the layer can promise, too: the proxy denies an action before it leaves the machine; the SDK evaluates in-process but is advisory, since a non-cooperating agent never calls it; eBPF tells you an action happened.

Last updated: 2026-08-06 by Chisanan232

Self-hosting the open-source stack

Agent Assembly is open source. You can self-host it yourself — stand the infrastructure up, run it, and maintain it — using the sample Docker Compose stack in examples/docker-compose/. This page is the quick path for developers: it shows the infrastructure architecture (which containers exist, who each is for, and what each does), the exact configuration, and how to bring it up.

“Open source” here means scope, not a crippled build. Self-hosting runs the components that live in this open-source repository. The hosted SaaS edition additionally runs everything for you as a managed, multi-tenant service and adds the cloud/enterprise control-plane features that live outside this repo (managed persistence, SSO, compliance reporting). Nothing here is deliberately feature-limited — the example simply starts with the components that already ship a container image today.

Infrastructure architecture

The full self-host topology is a short, end-to-end chain. Operators work in the dashboard; the dashboard reads everything through the REST API (aa-api); the API fronts the gateway (the brain), which evaluates policy and saves governance records to persistence; and your agents run co-located with an aa-runtime enforcement sidecar, which checks the actions it receives with the gateway. So the very actions your agents take are recorded in persistence and surface back in the dashboard:

you ⇄ dashboard ⇄ aa-api ⇄ aa-gateway ⇄ persistence ⇆ aa-runtime ⇄ your agents

flowchart TB
    user(["Operator — you, in a browser"])

    subgraph present["Observe and manage"]
        dash["dashboard<br/>single container · React / Vite"]
        api["aa-api<br/>REST / OpenAPI :7700"]
    end

    gw["aa-gateway<br/>registry · policy · budgets · audit<br/>gRPC :50051"]
    db[("persistence — you run and manage<br/>Postgres / TimescaleDB + cache")]

    subgraph workload["Your workload — agent + program, co-located"]
        agent["your agent(s)"]
        rt["aa-runtime<br/>enforcement sidecar · :8080"]
    end

    user -->|HTTPS| dash
    dash <-->|HTTP / WS :7700| api
    api <-->|read model| gw
    gw <-->|audit and state| db
    agent <-->|IPC over UDS socket| rt
    rt -->|CheckAction gRPC :50051| gw
    gw -->|Allow / Deny| rt
    gw -->|save governance records| db

Two things to read from it:

• The observability loop. Your agents + aa-runtime produce the governance data (decisions, audit, budget usage); the gateway persists it; the dashboard reads it back through the API. That is how what your agents do shows up on screen.
• What runs where. The dashboard is a single container; persistence is a standard datastore you run and manage (e.g. Postgres / TimescaleDB); the gateway + API are the control plane; and each agent runs next to its own aa-runtime sidecar, sharing a Unix-domain socket.

Containers — for whom, for what

Everything above is open source in this repository. Today aa-runtime ships a published image and aa-proxy builds from a Dockerfile; aa-gateway, aa-api and dashboard you build from source (first-class images are tracked as follow-up); and persistence is any standard Postgres / TimescaleDB you run. The hosted SaaS edition runs this whole stack managed for you and adds the cloud / enterprise control-plane features that live outside this repo.

What the example Compose wires today

The sample docker-compose.yml starts the subset that ships container images out of the box — your agent placeholder, its aa-runtime sidecar, and the optional egress proxy — so you see enforcement working immediately, then grow toward the full topology above by adding persistence, gateway, API and dashboard.

flowchart LR
    subgraph compose["docker compose — your machine or CI"]
        stub["agent-stub<br/>(replace with your agent)"]
        rt["aa-runtime<br/>enforcement sidecar<br/>:8080 health and metrics"]
        proxy["aa-proxy<br/>egress MitM :8899<br/>optional · proxy profile"]
        pol[/"policy.toml<br/>bind mount"/]
        sock(["aa-runtime-socket<br/>shared UDS volume"])
    end
    stub <-->|IPC over shared UDS socket| sock
    rt <--> sock
    pol -->|AA_POLICY_PATH| rt
    stub -.->|outbound HTTPS| proxy
    proxy -.->|decisions| rt

The compose file (examples/docker-compose/docker-compose.yml) defines these services. Values below are taken directly from that file.

Volumes

Environment variables

aa-runtime:

agent-stub:

aa-proxy (only under the proxy profile):

Quickstart

From a clone of the repository:

cd examples/docker-compose

# Runtime sidecar path (default profile: aa-runtime + agent-stub)
AA_API_KEY=dev-local-key docker compose up

aa-runtime starts, enforces locally from ../policy.toml, exposes the IPC socket at /tmp/aa-runtime-my-agent-001.sock, and serves health/metrics on :8080:

curl http://localhost:8080/ready
curl http://localhost:8080/health
curl http://localhost:8080/metrics

To additionally build and run the optional egress proxy on :8899:

AA_API_KEY=dev-local-key docker compose --profile proxy up

Tear down when finished:

docker compose down
# or, if you started the proxy profile:
docker compose --profile proxy down

Replacing the agent stub

agent-stub is an alpine placeholder (the Python SDK is not yet published — tracked in AAASM-55). To run a real agent, replace its image: with your agent image, keep AA_AGENT_ID identical to aa-runtime, and keep the aa-runtime-socket volume mounted at /tmp. See the example’s README for details.

Configuring the aa-api service

Once you grow the stack past the runtime-only quickstart and run the aa-api control-plane service (the one the dashboard reads), a few AA_* environment variables on that service shape what operators see and how they sign in. The full reference lives in Configuration → aa-api server environment variables; the self-host essentials:

Native email/password login requires a Postgres-backed deployment. The in-memory / runtime-only quickstart above stays API-key-only. Once aa-api is backed by Postgres, human operators can sign in with accounts — GET /api/v1/auth/methods advertises whether the password path is available, and the login page degrades honestly when it is not. See Authentication for the account, invite, and reset flows.

When you want it fully managed

If you would rather not run and maintain the infrastructure yourself — and want the managed, multi-tenant control plane with durable audit history, the operator dashboard, central registry, team budgets, SSO and compliance reporting — use the hosted SaaS edition, which runs the complete stack for you.

Last updated: 2026-08-06 by Chisanan232

Authentication

Agent Assembly’s aa-api supports two credential paths, side by side:

• API keys — for machines. SDKs, agents, and scripts authenticate programmatically with an API key. This path is unchanged and is available on every deployment.
• Native email/password accounts — for human operators at the dashboard. This is an additive path for people; it never replaces the API key. It is only available on a Postgres-backed deployment (see below).

Both paths mint the same scoped JWT that every RBAC gate already reads, so enabling accounts changes nothing about how authorization works — it only adds a second way for a human to obtain that token.

Which methods a deployment offers

A deployment advertises its available credential methods through a public endpoint, so the dashboard never presents a login form the backend cannot serve:

$ curl http://localhost:7700/api/v1/auth/methods
{"methods":["api_key"]}                 # in-memory deployment (API key only)

$ curl http://localhost:7700/api/v1/auth/methods
{"methods":["api_key","password"]}      # Postgres-backed deployment

password appears only when a Postgres account store is configured. On an in-memory deployment the native-auth endpoints below respond 503 Service Unavailable and the dashboard shows only the API-key path.

Native accounts require Postgres. Passwords must be stored durably and safely, which an in-memory map cannot do across a restart, so the account endpoints are Postgres-gated. In-memory deployments stay API-key-only. This is a deliberate, surfaced limitation — not a hidden failure.

The API-key path (machines)

Unchanged. A caller exchanges an API key for a scoped JWT:

$ curl -X POST http://localhost:7700/api/v1/auth/token \
    -H "Authorization: Bearer <api-key>"

Use this for SDKs and agents. It works on every deployment, with or without Postgres.

The native-account path (human operators)

When a Postgres store is configured, aa-api mounts a set of account endpoints under /api/v1/auth:

The access token is short-lived (15 minutes) and returned in the response body; the refresh token is delivered as an HttpOnly; Secure; SameSite=Strict cookie scoped to /api/v1/auth, and is rotated on every refresh. remember_me on login extends the refresh lifetime from 12 hours to 30 days.

First user is admin, then invite-only

On a fresh instance the users table is empty, so registration bootstraps:

1. Bootstrap. The first account created via POST /api/v1/auth/register becomes the owner of the single default workspace. Registration is open only for this first account.
2. After bootstrap. Once any account exists, register returns 403 (registration closed). New accounts are created by an admin: POST /api/v1/auth/invite (admin scope) mints a single-use, expiring invite token; the invitee sets their password via POST /api/v1/auth/invite/accept.

An invite token is returned to the inviting admin exactly once (only its hash is stored) and expires after 7 days. Deliver it to the invitee out of band.

Opening self-registration (optional)

To let anyone self-register (not just the first user), set:

AA_AUTH_OPEN_REGISTRATION=true

The default is false (closed — first-user-then-invite). Only the truthy spellings 1, true, or yes (case-insensitive) enable it; any other value or leaving it unset keeps registration closed. When open registration is enabled, accounts created after the bootstrap owner receive the developer role.

Password policy

Passwords are hashed with argon2id and must be at least 12 characters. A shorter password is rejected with 422. Login is enumeration-safe: an unknown email and a wrong password both return a uniform 401, and repeated failures lock the account (423 with a Retry-After header) after 5 attempts for 15 minutes.

Password-reset email (SMTP)

Password reset (POST /api/v1/auth/password/reset) needs to deliver a reset token to the account owner by email. aa-api ships a pluggable SMTP mailer configured entirely through environment variables:

When AA_SMTP_HOST is set, aa-api builds a real SMTP transport (STARTTLS, authenticated when a user + pass are supplied) and password-reset emails are delivered.

Canonical production sender (AAASM-5521)

The no-reply@localhost default is intentionally a safe, unconfigured placeholder — it keeps a self-hosted deployment that never wired up SMTP from looking production-ready. A production deployment of the hosted service must set AA_SMTP_FROM to a real, authenticated sender on the dedicated transactional subdomain:

AA_SMTP_FROM=no-reply@mail.agent-assembly.com

This keeps application (transactional) mail off the human Google Workspace sending reputation, matching the boundary described for the SaaS mailer. The DKIM/SPF/return-path DNS that makes mail.agent-assembly.com deliverable is owned by the DNS ticket (AAASM-5517) and is not part of aa-api. Setting AA_SMTP_FROM to a sender whose domain is not actually verified with the SMTP provider will send mail that fails authentication — configure the provider and DNS first. Self-hosters running their own relay should set AA_SMTP_FROM to a sender on their own verified domain.

When SMTP is not configured

When AA_SMTP_HOST is unset, aa-api falls back to a logging mailer: it does not send anything, it logs that an email would have been sent (recipient and subject only — never the token). The deployment still boots and the reset endpoint still behaves correctly:

• POST /api/v1/auth/password/reset always returns 202 Accepted, whether or not the email exists and whether or not mail can be delivered. This is deliberate — the response must never reveal which addresses are registered.
• With no SMTP configured, no reset email is actually sent; the operator sees the log line instead. Users cannot self-serve a password reset until SMTP is wired up.

The same fallback applies if AA_SMTP_HOST is set but the transport cannot be built (a bad host or credential): aa-api logs a warning and falls back to the logging mailer rather than refusing to start.

Related

• Configuration — environment-variable reference, including the auth and SMTP variables.
• Self-hosting — the Postgres-backed stack that unlocks native accounts.

Last updated: 2026-08-04 by Claude Code

Governed container base images

Agent Assembly publishes a set of governed language base images to GitHub Container Registry (GHCR). Each one bundles the aasm operator binary and the Agent Assembly SDK for its language, so a containerized agent is governed on its first run with no extra install step — you just build your agent FROM one of them.

These images are the convenience on-ramp for the in-process (SDK) interception layer. They are optional: you can always install the SDK and aasm yourself. See Choosing interception layers for the bigger picture.

The images

Three languages × three runtime versions = 9 images, under ghcr.io/ai-agent-assembly/. Each language also has its own container guide — with the FROM example, install command, and SDK_VERSION usage tailored to that language:

Each is a small two-stage build (the aasm CLI is compiled and copied into an official python / node / golang slim base) and is published for linux/amd64 and linux/arm64. The enforcement sidecar image ghcr.io/ai-agent-assembly/aa-runtime is documented separately under Self-hosting.

Tags: how to choose one

Every image is published under three kinds of tag. Which you use is the single most important choice for reproducibility:

The <core-version> coordinate is the Agent Assembly core release (the same version as the aasm CLI baked into the image and the aa-runtime sidecar). So all of python:3.14-slim-vX.Y.Z, node:24-slim-vX.Y.Z, … and aa-runtime:vX.Y.Z line up on one version.

Quick start

Build your agent on top of an image:

# Pin the immutable tag for a reproducible build (recommended).
FROM ghcr.io/ai-agent-assembly/python:3.14-slim-v0.0.1-rc.1

WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt   # your agent's deps

CMD ["python", "agent.py"]

What you get inside the image:

• aasm --version works — the operator CLI is on PATH.
• The SDK is importable with no extra install — from agent_assembly import init_assembly (Python), require('@agent-assembly/sdk') (Node), the go-sdk module (Go).

To actually enforce policy, run your agent alongside the aa-runtime sidecar (the authoritative chokepoint). The docker compose example in the repo (examples/docker-compose/) wires this up; see Self-hosting.

Choosing the SDK version — the SDK_VERSION build-arg

The SDK that ships in the image is controlled by an optional SDK_VERSION build argument:

# Default — no build-arg: installs the latest STABLE SDK release, or the latest
# pre-release when no stable exists yet.
docker build -f docker/Dockerfile.python-3.14-slim .

# Explicit pin — exactly this released SDK (reproducible).
docker build -f docker/Dockerfile.python-3.14-slim \
  --build-arg SDK_VERSION=0.0.1b5 .

The default resolution is uniform across all three SDKs — latest stable release, falling back to the latest pre-release — and matches how the install-cli.sh one-liner resolves the CLI, so the whole product behaves consistently.

The pre-built images that Agent Assembly publishes always pin SDK_VERSION explicitly (to the release that is compatible with that core version), so a published immutable tag is fully reproducible. The default only applies when you build an image yourself without passing the arg.

Why it’s designed this way

The image carries two versioned things, and the design makes the relationship explicit:

• The core version is the axis you choose. It is the image-tag coordinate (…-vX.Y.Z) and the aasm CLI compiled into the image. Picking an immutable tag picks a core release.
• The SDK version is a dependent value. Each core release ships with the SDK release that is compatible with it; the SDK versions independently of the core (the Python/Node/Go SDKs do not share a version number with the core), so the image resolves the SDK explicitly rather than assuming “SDK version = core version”.

That is why the tag is keyed on the core version while the SDK is pinned through a separate manifest. The full rationale — including the move away from the old divergent per-language install defaults — is recorded in ADR 0009.

Recommended best practices

What the Agent Assembly team recommends:

1. Pin the immutable tag in CI and production. Use …/<lang>:<runtime>-<core-version>, never :latest, for anything you ship or build repeatedly. It guarantees the same aasm + SDK every time.
2. Use the moving <lang>:<runtime> tag for local development, where “the newest release for this runtime” is convenient and reproducibility matters less.
3. Pin SDK_VERSION when you need an exact SDK for compliance, audits, or to match a specific gateway/runtime — don’t rely on the floating default for shipped images.
4. Keep the image’s core version and your aa-runtime sidecar on the same release. They are designed and tested as a set; consult the compatibility matrix before mixing versions.
5. Pair the image with the aa-runtime sidecar (and, where needed, the proxy or eBPF layers) for authoritative enforcement. The in-process SDK layer is the fastest path but is not, by itself, a security boundary — see Choosing interception layers.
6. Rebuild on each core release to pick up SDK and CLI fixes; bump the pinned -<core-version> tag deliberately rather than tracking a moving tag silently.

Current status

The bundled SDK runs in its offline / observe path today — the native socket-dialing runtime client is not yet shipped inside these images, so live in-process SDK → aa-runtime transport from within the image is a tracked follow-up. Authoritative enforcement is still fully available via the aa-runtime sidecar (and the proxy / eBPF layers); the images simply give your agent the SDK and CLI pre-installed. Watch the release notes for when the native client lands.

Reference

• Source Dockerfiles: docker/Dockerfile.<lang>-<runtime> in the agent-assembly repo.
• Design: ADR 0009 — Versioned Base-Image Tags & SDK Pinning.
• Running the sidecar: Self-hosting (open source).
• Installing the CLI directly: Installation.
• Version compatibility: Compatibility matrix.

Last updated: 2026-06-26 by Bryant

Runnable examples

The pages in this guide explain how governance works. When you want to run it, the framework-specific, end-to-end examples live in the dedicated examples repository rather than in this book — that keeps the runnable code versioned and testable on its own, while these pages stay focused on the concepts.

Want to stand up the infrastructure itself? The Self-hosting guide walks through the open-source Docker Compose stack — its architecture, which containers run (and who each is for), and how to set up, run, and maintain the program’s infra locally. For the wiring diagram behind that stack — how a single agent action travels across every hop and the real config knob at each one — see the Infrastructure overview.

Every example is governed by the same three-layer interception model described in Choosing interception layers: a gateway as the brain, at least one interception layer (SDK shim, aa-proxy sidecar, or eBPF), and a policy. Pick the language you are integrating, or browse the cross-cutting scenarios:

• Node — examples-repo/node
• Python — examples-repo/python
• Go — examples-repo/go
• Scenarios (cross-cutting: approval-gates, audit-trace, budget-limits, policy-enforcement, sidecar-runtime) — examples-repo/scenarios

Per-SDK example docs

Each language SDK also publishes its examples as rendered documentation, with the governance walkthrough alongside the code. These are the same scenarios as the repo links above, presented in the SDK’s own docs site.

• Python — python-sdk examples
• Node — node-sdk examples
• Go — go-sdk examples

Last updated: 2026-07-23 by Bryant

Troubleshooting

Common local issues and the real diagnostics to resolve them. Every error message below is reproduced verbatim from the 0.0.1-beta.4 build.

aasm start fails: “failed to spawn aa-gateway”

$ aasm start --mode local --port 7391
aasm start: failed to spawn aa-gateway: No such file or directory (os error 2)

Cause. aasm start shells out to a separate aa-gateway binary, which must be on your PATH.

Fix. Build it and put target/debug on PATH:

$ cargo build -p aa-gateway --bin aa-gateway
$ export PATH="$PWD/target/debug:$PATH"
$ aasm start --mode local --port 7391

aasm start fails: “–policy is required in legacy-grpc mode”

$ aasm start
Error: "--policy is required in legacy-grpc mode"
aasm start: gateway did not become ready within 5.000335375s

Cause. The aa-gateway binary defaults to its legacy gRPC mode, which requires a policy file. For a local control plane with the HTTP API and dashboard, you want local mode, which does not.

Fix. Run local mode directly:

$ aa-gateway --mode local
Agent Assembly [local mode] v0.0.1-beta.4
  Listening:  http://127.0.0.1:7391
  Dashboard:  http://127.0.0.1:7391/
  Storage:    /Users/you/.aasm/local.db (SQLite)

  Ctrl+C to stop.

For the legacy gRPC server, supply a policy: aa-gateway --policy policy-examples/low-risk.yaml.

CLI commands say the gateway is “unreachable”

$ aasm status
Agent Assembly Status
─────────────────────────────────────
  Gateway:   http://localhost:8080
  Health:    ✗ unreachable
─────────────────────────────────────
...
Error: gateway is not running. Start it with: aasm start

$ aasm version
+-----------+---------------+-------------+
| COMPONENT | VERSION       | STATUS      |
+=========================================+
| cli       | 0.0.1-beta.4  | -           |
|-----------+---------------+-------------|
| gateway   | -             | unreachable |
|-----------+---------------+-------------|
| api       | -             | unreachable |
+-----------+---------------+-------------+

Cause. The CLI defaults to the SaaS control-plane API on http://localhost:8080. The local-mode gateway serves its API on 7391, not 8080, so the default target is unreachable.

Fix. Point the CLI at the local API:

$ aasm --api-url http://127.0.0.1:7391 status
Agent Assembly Status
─────────────────────────────────────
  Mode:      local
  Gateway:   http://127.0.0.1:7391
  Storage:   sqlite
  Version:   0.0.1-beta.4
  Uptime:    2m 24s
  Health:    ✓ ok
─────────────────────────────────────

To avoid repeating the flag, save a named context with aasm context or set the API URL in ~/.aa/config.yaml.

aasm gateway status says “not running” even though local mode is up

$ aasm gateway status
Gateway: not running

Cause. aasm gateway status tracks the legacy gRPC gateway via its PID file. A gateway started in local mode (aa-gateway --mode local) is a different process and is not reflected here.

Fix. Check local-mode liveness with the HTTP status instead:

$ aasm --api-url http://127.0.0.1:7391 status

or hit the health endpoint directly: curl http://127.0.0.1:7391/healthz.

A dashboard page loads but its tables stay empty / skeleton

Cause. The dashboard SPA served by the local-mode gateway can render its chrome and page shells, but its data endpoints (/api/v1/fleet, /api/v1/policies, …) are served by the SaaS/cloud control plane on port 8080, which is not part of the open-source local runtime. With only the local gateway running, data panels stay empty or in their loading state.

Fix. Connect a control plane that serves the /api/v1/* data routes (the hosted backend), or use the CLI (aasm agent list, aasm policy list, aasm cost summary) against the local API for the same data in the terminal. See Observe in the dashboard.

policy validate prints “Unknown key … will be ignored”

$ aasm policy validate policy-examples/medium-risk.yaml
warning: tier — Unknown key 'tier' will be ignored
warning: rules — Unknown key 'rules' will be ignored
warning: notifications — Unknown key 'notifications' will be ignored
Policy is valid: policy-examples/medium-risk.yaml

Cause. These are warnings, not errors — the policy still validates. The keys tier, rules, notifications, and similar are not part of the schema the gateway enforces; the supported spec sections are network, schedule, budget, data, tools, capabilities, approval, and scope.

Fix. Move the intended behaviour into a supported section (e.g. express allow/deny via capabilities or tools, gating via approval), or ignore the warnings if the extra keys are intentional annotations. The capability-policy.yaml example validates with no warnings and is a good reference shape.

A wildcard egress host is denied in policy simulate

If aasm policy simulate denies a host that your *.example.com allowlist entry should permit, this is expected: the simulator’s decision path uses an exact host comparison, while the live aa-proxy uses the glob-aware matcher. Confirm the host against the running proxy rather than treating the simulation deny as a real block — see the caveat in Enforce an egress policy.

Quick reference

Last updated: 2026-06-24 by Bryant

Security Model — Overview

Agent Assembly governs AI agents that you do not fully trust, running inside processes you do not fully control. The Security Model describes what the system protects, against whom, and how — and, just as importantly, where it refuses to place its trust.

This section is the why. For the how — concrete crates, types, and data paths — follow the cross-links into Architecture.

What the Security Model protects

An AI agent is, from a security standpoint, an attacker-shaped component: it executes language-model output, calls external tools, opens network connections, reads files, and spends money — all driven by prompts that may be adversarially crafted (prompt injection) or by a model that has been compromised or simply behaves unpredictably. The Security Model exists to keep that component inside a governed boundary. Concretely it protects:

• Tool and capability use — an agent may only invoke the tools its policy permits. Denied tool calls are refused before they execute.
• Network egress — outbound connections are constrained to an allowlist; exfiltration to an arbitrary host is blocked.
• Credentials and sensitive data — API keys, private keys, and connection strings are detected and redacted on every path before they are forwarded or persisted, so a leaked secret never lands in an upstream request or an audit record.
• Spend — per-team and per-org budgets cap how much an agent can cost; a runaway agent is denied or suspended when it exceeds its limit.
• The audit trail itself — every governed action produces a sanitized, tamper-evident record, so the system’s own evidence cannot be quietly poisoned with raw secrets or per-event noise.

Defense-in-depth philosophy

The Security Model rests on three principles, each developed in its own page.

1. Layered interception — see the action before you can govern it

To govern an action the system must first observe it. Agent Assembly intercepts at three independent layers — the in-process SDK shim (aa-sdk-client), the sidecar proxy (aa-proxy), and kernel-level eBPF (aa-ebpf) — ordered lowest-latency-first and highest-detection-authority-first. The layers are not alternatives; they stack, so an action that slips past one is caught by the next. Coverage is the union of the layers you deploy.

2. The SDK is not a trust boundary — the runtime is authoritative

The fastest layer runs inside the agent’s own process, which is exactly the component we do not trust. So the system treats SDK-side checks as best-effort advisory only and re-does the authoritative work at a trusted chokepoint: the runtime (aa-runtime) re-scans, re-redacts, and re-normalizes every event unconditionally, and the gateway (aa-gateway) is the sole source of truth for policy. This is recorded as a formal decision in ADR 0002 and detailed in Trust boundaries.

Invariant: nothing the SDK asserts can shorten the trusted side’s work. Position — not code — confers authority. The same aa-security scanner is advisory inside the SDK and authoritative inside aa-runtime.

3. Fail-closed by default

When the system cannot make a safe decision, it denies. An empty policy cascade returns a fail-closed Deny (aa-gateway/src/engine/decision.rs), and a secret-bearing field too large to fully scan is redacted whole rather than forwarded raw (aa-runtime/src/pipeline/enforcement.rs, OversizedPolicy::RedactWhole). See Protection and enforcement.

How the pages fit together

Last updated: 2026-07-15 by Chisanan232

Threat model

This page enumerates what the Security Model defends: the assets worth protecting, the adversaries who threaten them, and the concrete threats each control answers. It is specific to Agent Assembly — the system that governs AI agents at the three interception layers and a central gateway.

Assets

Adversaries

The model assumes the agent’s own process is not trusted. The relevant adversaries are:

• The prompt-injected agent. A legitimate, SDK-adopting agent whose model has been steered by adversarial input into making tool calls, network requests, or data accesses its operator never intended. It is cooperative at the binary level but hostile at the behavioral level.
• The compromised / modified agent. An agent whose code has been altered — including one running a patched, outdated, or stubbed SDK — that deliberately tries to suppress, weaken, or skip the in-process checks.
• The bypassing agent. An agent that ignores the SDK entirely and makes raw syscalls, opens its own sockets, or links TLS directly to avoid the fastest interception layer.
• The careless integrator. Not malicious, but ships secrets in tool arguments or LLM payloads, or wires an agent to an over-broad capability set.

Trust posture. Because the SDK runs inside an attacker-controllable process, any guarantee anchored in the SDK is not a guarantee. Security must hold even when the SDK does nothing — see Trust boundaries and ADR 0002.

Threat scenarios

1. Unauthorized tool call — a prompt-injected agent invokes a tool outside its policy (e.g. terminal_exec, or read_file on /etc/...). Caught by the gateway tool allow/deny stage and, for MCP tools/call, by argument-level matching in the proxy (aa-proxy/src/intercept/mcp.rs).
2. Credential / data exfiltration — the agent embeds an API key in an LLM prompt or a tool argument and sends it upstream. The aa-security scanner detects the secret (via Aho-Corasick literal patterns) and redacts it before forward and before audit, on every path.
3. Network egress to an arbitrary host — the agent attempts to POST data to an attacker-controlled domain. The gateway’s network allowlist denies the request; the proxy enforces it at the wire even with no agent code change; eBPF SSL uprobes observe the plaintext if the agent bypasses both.
4. Policy evasion / SDK bypass — the agent disables, stubs, or skips the SDK scanner, or asserts an “already clean” marker. Defeated structurally: there is no trust marker on the wire, and aa-runtime re-scans unconditionally. This is proven by the bypass-resistance suite (aa-runtime/tests/aaasm_2568_gate_verification.rs).
5. Runaway spend — a looping agent issues unbounded LLM calls. The budget tracker denies further requests once the daily/monthly limit is met, or suspends the agent, per action_on_exceed.
6. Audit poisoning / secret leakage into logs — a sender emits raw prompts, full payloads, or per-beat heartbeat noise into the audit stream. The write-boundary sanitizer strips banned keys recursively and collapses heartbeats before anything reaches audit_logs.

STRIDE mapping

Each control is detailed in Protection and enforcement.

Release-time companion

This page is the durable catalogue, refreshed rarely. Its versioned, per-release operational counterpart is the release threat model: a versioned document reviewed on every release and rewritten in full at every major, with a “what does this release change about our exposure?” layer map.

Last updated: 2026-07-15 by Chisanan232

Release threat model

Threat-model version: 1 Last full refresh: v0.0.1-beta.3 (the current pre-release tip; this doc is seeded against it) Scope: the release process — what a release can newly expose, and which layer is supposed to stop it.

This is the versioned, operational threat model that is reviewed on every release and rewritten in full at every major. It is deliberately distinct from the conceptual threat model (the durable assets / adversaries / scenarios catalogue, which changes rarely): this page answers the narrower question “what does this release change about our exposure, and is each change covered?”

It is consumed by two operational artifacts:

• the trust-boundary review checklist — the per-release delta form a reviewer fills in, and
• the /release-security-gate SKILL — the release-gate review scaled by release type (it wraps the built-in /security-review scanner).

Why a threat model needs a version

A threat model that is not versioned silently goes stale. What was modeled at v1 stops describing what actually ships at v3 — a new endpoint, a loosened policy default, a new egress path — and an attacker operates precisely in that gap between modeled and shipped. Pinning a version number plus a per-major full refresh makes staleness visible and auditable: if the Threat-model version has not advanced across a major, that is itself a finding.

The layered “assume previous layer breached” map

The release threat model inherits the defense-in-depth layer chain from Three-layer defense in depth and Trust boundaries, and adds the explicit zero-trust assumption for each layer: every layer assumes the layer before it has already been breached. A release that changes a layer must answer “does the next layer still hold if this one is bypassed?”

The invariant across the chain: position — not code — confers authority. A release must never move an authoritative guarantee up the chain into a layer that assumes itself breached (e.g. relocating the only credential scan back into the SDK).

What a release can change about exposure

Every release is reviewed for these delta classes (enumerated row-by-row in the trust-boundary review checklist):

• A new endpoint or RPC method (new attack surface to authn/authz).
• A loosened policy default (a default that now permits what it used to deny).
• A new network egress path (aa-gateway/src/policy/network.rs).
• A new IPC / UDS surface between SDK ↔ runtime ↔ gateway.
• A changed sanitizer / redaction scope (a field newly carried, or newly exempted from scanning).
• A new dependency or advisory (a transitive CVE shipping in the release).

When this is refreshed

Revision table

One row per full refresh (each major). Delta touches are recorded in the per-release sign-off artifact instead, to keep this table a clean major-version history.