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 in an immutable audit trail.

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 every action against policy and budget, and records the outcome in an immutable 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 lets the runtime see what an agent does no matter how the agent is built.

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: it checks every action an agent tries to take 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 that an AI agent cannot walk around.

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 every agent did and why.

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. Every time an agent tries to call a tool, reach the network, or spend money on a model call, the runtime evaluates that action against a policy and a budget, returns allow or deny before the action runs, and writes an immutable audit record of the decision.

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.
• An immutable audit trail. Every decision — allow and deny alike — is recorded, giving teams a complete, tamper-evident account of agent behavior for debugging, incident response, and compliance.
• Defense that does not depend on the agent. Enforcement is layered across three independent interception points (see the three-layer model), so governance holds even when an agent skips its SDK or actively tries to evade it.

Crucially, the agent does not have to cooperate. The whole point is that governance is enforced around the agent, by infrastructure the agent does not control. The Security Model section makes the trust boundaries explicit.

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-06-12 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 immutable, append-only record of every decision the gateway makes — both allows and denies — together with the action that prompted it. Because it is tamper-evident and complete, it answers the accountability question for any 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 everything — the three- layer interception model explains how the runtime actually sees an agent’s actions in order to govern them.

Last updated: 2026-06-11 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 catches actions the higher layers never saw — including deliberate attempts to bypass the SDK.

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 floor that catches what slips past both. Run all three and an action has nowhere to hide.

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[("Immutable 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-06-11 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-06-11 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.

Quick-install script

The one-line installer downloads the matching pre-built tarball plus its SHA256SUMS file from the GitHub Release, verifies the checksum, and installs the aasm binary:

curl -sSf https://raw.githubusercontent.com/ai-agent-assembly/agent-assembly/master/scripts/install-cli.sh | sh

By default the binary is installed to /usr/local/bin if that directory is writable, otherwise to ~/.local/bin (always user-writable, no sudo needed). The installer script lives in the repo at scripts/install-cli.sh.

A short hosted alias (https://install.ai-agent-assembly.dev — hosted install script, coming soon) is planned but not yet live — use the raw.githubusercontent.com URL above for now.

If the install directory is not on your PATH, the script prints the line to add to your shell profile, for example:

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

Pin a version or change the install directory

The installer honors these environment variables:

# Install a specific release tag (default: latest)
AASM_VERSION=v0.0.1-alpha.5 curl -sSf https://raw.githubusercontent.com/ai-agent-assembly/agent-assembly/master/scripts/install-cli.sh | sh

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

Supply-chain verification (checksum + cosign)

The installer always enforces a SHA-256 checksum: it downloads SHA256SUMS and aborts if the tarball’s hash does not match. The checksum file itself is additionally signed with cosign (keyless, via GitHub OIDC — Fulcio cert + Rekor log). If cosign is installed locally, the installer verifies that signature against the release workflow’s identity before trusting the checksums. To make a missing/unverifiable signature fatal:

AASM_REQUIRE_SIGNATURE=1 curl -sSf https://raw.githubusercontent.com/ai-agent-assembly/agent-assembly/master/scripts/install-cli.sh | sh

Releases published before signing was added carry no cosign bundle; with the default AASM_REQUIRE_SIGNATURE=0 the installer warns and falls back to checksum-only (the SHA-256 check is never skipped).

Homebrew (macOS / Linux)

Install the latest tagged aasm release from the Homebrew tap:

brew install ai-agent-assembly/homebrew-agent-assembly/aasm

Pre-built binaries (manual)

Each GitHub Release publishes per-platform tarballs plus a SHA256SUMS file and a SHA256SUMS.cosign.bundle signature. Tarballs are named aasm-<arch>-<os>.tar.gz, where <arch> is x86_64 or aarch64 and <os> is apple-darwin (macOS) or unknown-linux-gnu (Linux).

To install and verify by hand:

VERSION=v0.0.1-alpha.5
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

Build from source

Contributors and anyone who wants the bleeding edge can build from the Cargo workspace. This needs the build prerequisites (Rust ≥ 1.75 and protoc).

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

The compiled binary is at ./target/debug/aasm. Add it to your PATH or run it by path. You can also install it onto your PATH with Cargo:

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

The eBPF-target crates (aa-ebpf-probes, aa-ebpf-programs) are intentionally outside the workspace and are not built by cargo build -p aa-cli. See Requirements.

Verify the install

Confirm the binary is on your PATH and runs:

$ aasm --version
aasm 0.0.1-alpha.5

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-alpha.5 | -           |
|-----------+---------------+-------------|
| 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-06-12 by Chisanan232

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.

Note the two prefixes: AASM_* variables configure the CLI surface, while AA_* variables configure the underlying daemons the CLI launches (gateway, proxy). They are not interchangeable.

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-alpha.5",
    "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-06-11 by Chisanan232

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-alpha.5 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 every action to the gateway over gRPC.
• Sidecar proxy (no code changes): run aasm proxy start to intercept the agent’s outbound HTTPS and forward governance decisions to the gateway.
• eBPF (Linux only): kernel hooks catch everything else, including bypass attempts.

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-06-12 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.

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.

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. The source tree also defines aasm run (launch a governed AI dev tool) and aasm tools (discover installed AI dev tools). Both are gated behind the devtool region in aa-cli/src/commands/mod.rs and aa-cli/Cargo.toml and are stripped from the published crate by .ci/strip-for-publish.sh before release. They are intentionally not documented here because they are not part of the published aasm surface.

Last updated: 2026-06-11 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
  ID        NAME            FRAMEWORK   STATUS   SESSIONS   VIOLATIONS   LAST EVENT
  a1b2…     research-bot    langgraph   active   3          0            2m ago tool_call

Pending Approvals: 1  (oldest 2m 15s)
Budget: $12.50 / $50.00 daily  ███████░░░░░░░░░░░░░  25%

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-06-11 by Chisanan232

aasm agent

Manage monitored agent processes registered with the gateway.

Synopsis

aasm agent <SUBCOMMAND> [OPTIONS]

All subcommands accept the global options, including --output table|json|yaml.

aasm agent list

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

Options

Example

aasm agent list --status Active --framework langgraph

ID        NAME           FRAMEWORK   VERSION   STATUS    TOOLS
a1b2c3…   research-bot   langgraph   1.2.0     Active    search, fetch

aasm agent inspect

Render a detailed key-value view of a single agent: identity, status, tools, metadata, active sessions, recent events, and recent trace session IDs.

Arguments

Example

aasm agent inspect a1b2c3d4e5f600112233445566778899

Agent a1b2c3d4…
  Name:        research-bot
  Framework:   langgraph 1.2.0
  Status:      Active
  PID:         48213
  Sessions:    3
  Violations:  0
  Tools:       search, fetch, summarize
  Recent traces:
    7f3a…  2026-06-09T14:02:11Z   (aasm trace 7f3a…)

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

Suspended a1b2c3… : Active → Suspended

aasm agent resume

Resume a previously suspended agent.

Arguments

Example

aasm agent resume a1b2c3…

Resumed a1b2c3… : Suspended → Active

aasm agent kill

Deregister and terminate an agent.

Arguments / options

Example

aasm agent kill a1b2c3… --force

Killed a1b2c3… — deregistered and terminated.

Last updated: 2026-06-11 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

Applied policy 9f2c1a (version 2026-06-09T14:00:00Z) — active, 12 rules

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: 412 events, 3 would-be violations
  deny  file_write  /etc/passwd   (rule: block-system-paths)
exit status: 1

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 valid — 12 rules

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      VERSION                  ACTIVE   RULES
9f2c1a    2026-06-09T14:00:00Z     yes      12
7ab310    2026-06-01T09:30:00Z     no       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-06-11 by Chisanan232

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 (tables render via box-drawing trees for tree/lineage).

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

research-bot (a1b2c3…)
├── fetch-worker (d4e5f6…)
│   └── parse-worker (778899…)
└── summarize-worker (aabbcc…)

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.

aasm topology lineage 778899… --show-permissions

root-bot (a1b2c3…)
└── fetch-worker (d4e5f6…)
    └── parse-worker (778899…)   ← target

aasm topology stats

Show aggregate topology statistics — total/root/active/suspended counts, max depth, team sizes, and depth/spawn histograms. Takes no flags of its own (uses the global --output).

aasm topology stats --output json

Total agents:    42
Root agents:     5
Max depth:       4
Active:          38   Suspended: 3   Deregistered: 1
Teams:           5
Avg children/parent: 2.31

Last updated: 2026-06-11 by Chisanan232

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

Resolved al-301.

Last updated: 2026-06-11 by Chisanan232

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.

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.

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

▶ ap-78  a1b2c3…  network_egress  api.openai.com   3m 00s
  a approve   r reject   ↑/↓ select   q quit

Last updated: 2026-06-11 by Chisanan232

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

SEQ   TIMESTAMP             AGENT     EVENT             RESULT
142   2026-06-09T14:01:00Z  a1b2c3…   PolicyViolation   deny

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

✓ chain valid — 412 entries, genesis → entry 0xab12…

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-06-11 by Chisanan232

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

session 7f3a1c2b
├─ 🧠 llm: gpt-4 (1200ms)
│  ├─ 🔧 tool_call: search (340ms)
│  │  └─ 📥 tool_result: search (12ms)
│  └─ ⛔ deny: file_write — path outside allowlist
└─ 🧠 llm: gpt-4 (800ms)

Timeline view:

aasm trace 7f3a1c2b --format timeline

llm: gpt-4        ████████████████████  1200ms
tool_call: search ██████                 340ms
llm: gpt-4        █████████████          800ms

Last updated: 2026-06-11 by Chisanan232

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

Cost Summary (month, 2026-06)
  Total: $312.40 / $1,000.00  (31.2%)

  AGENT      MONTHLY SPEND
  a1b2c3…    $180.10
  d4e5f6…    $132.30

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 (2026-06-09, day 9 of 30)
  Current daily spend:      $12.50
  Projected monthly spend:  $375.00
  Monthly limit:            $1,000.00
  Projected utilization:    37.5%

Last updated: 2026-06-11 by Chisanan232

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.

aasm dashboard start --port 8088 --open

Dashboard serving at http://127.0.0.1:8088  (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 server stopped.

Last updated: 2026-06-12 by Chisanan232

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 from $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-06-11 by Chisanan232

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, then ./target/release.

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

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-06-11 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

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 aa-gateway (background, or foreground with --foreground).
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 (pid 48213)
  Gateway:    http://localhost:7391
  Dashboard:  http://localhost:7391

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

Sent SIGTERM to pid 48213; exited gracefully.

Last updated: 2026-06-11 by Chisanan232

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 run: ./tool.wasm
  Outcome:    completed
  Fuel used:  3,201,884 / 50,000,000
  Wall time:  812ms / 10000ms

aasm sandbox info

Show the default sandbox runtime limits. Takes no arguments.

aasm sandbox info

Default sandbox limits:
  Fuel:           10,000,000 units
  Memory pages:   16  (1 MiB)
  Wall clock:     5000 ms

Last updated: 2026-06-11 by Chisanan232

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

NAME         API URL                       DEFAULT
production   https://api.example.com       *
staging      https://staging.example.com

aasm context set

Create or update a named context.

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

Saved context 'staging'.

aasm context use

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

aasm context use production

Default context set to 'production'.

Last updated: 2026-06-11 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

{
  "dry_run": true,
  "audit_events_scanned": 14293,
  "audit_events_dropped": 0
}

Last updated: 2026-06-11 by Chisanan232

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
gateway     0.0.1
api         0.0.1

JSON form:

aasm version --output json

Last updated: 2026-06-11 by Chisanan232

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-alpha.5 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
  run         Launch an AI dev tool (claude, codex, copilot, windsurf) with governance wiring
  sandbox     Run a WebAssembly tool inside the Agent Assembly sandbox
  tools       List and manage AI dev tools on this system
  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-11 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.

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.172 (Claude Code) | /opt/homebrew/bin/claude                                | L3Native         |
|---------------+-----------------------+---------------------------------------------------------+------------------|
| Codex         | codex-cli 0.135.0     | /opt/homebrew/bin/codex                                 | L2Enforce        |
|---------------+-----------------------+---------------------------------------------------------+------------------|
| GitHubCopilot | 1.388.0               | /Users/you/.vscode/extensions/github.copilot-1.388.0    | L1Observe        |
+---------------+-----------------------+---------------------------------------------------------+------------------+

The governance level reflects how deeply Agent Assembly can integrate with that tool — from L3Native (the tool exposes a hook the runtime wires into directly) down to L1Observe (the runtime can observe but not natively intercept, so the proxy and eBPF layers do the enforcing).

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-alpha.5
  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 — 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
--- 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

--- 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 two things that are doing real work:

• 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.

Step 4 — 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, every tool-call and outbound request routed through the gateway for an allow/deny decision, secrets scrubbed from the recorded environment, and a complete audit trail keyed to the agent, team, and trace you assigned in Step 3.

Last updated: 2026-06-11 by Bryant

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:

$ aasm proxy install-ca          # add the per-host 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 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-06-11 by Bryant

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-alpha.5 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-12 by Chisanan232

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 defense-in-depth that an agent cannot bypass — e.g. it shells out, writes files, or makes raw connections that skip both the SDK and the proxy. This is the catch-all backstop.

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. On Linux, eBPF sits underneath both as the bypass-proof floor.

aasm run reflects this in its governance level (see Govern an agent end-to-end): a tool reported as L3Native integrates at the SDK depth, while an L1Observe tool relies on the proxy and eBPF layers to do the actual enforcing.

Layer 2 in practice — the proxy

$ aasm proxy install-ca      # trust the per-host 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 code-free egress control, eBPF for a bypass-proof kernel backstop on Linux — all feeding one gateway and one audit log.

Last updated: 2026-06-11 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 agent-assembly-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.

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

Last updated: 2026-06-14 by Chisanan232

Troubleshooting

Common local issues and the real diagnostics to resolve them. Every error message below is reproduced verbatim from the 0.0.1-alpha.5 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-alpha.5
  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-alpha.5 | -           |
|-----------+---------------+-------------|
| 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-alpha.5
  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-11 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-06-11 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.

Last updated: 2026-06-11 by Chisanan232

Three-layer defense in depth

To govern an action, Agent Assembly must first observe it. It does so at three independent interception layers, each catching what the layers above it might miss, and routes every observed action to one central gateway for the decision. This page explains why the layers are arranged the way they are and how they compose so an agent cannot quietly slip through. For the policy decision itself, see Protection and enforcement; for how implementation maps to crates, see Architecture.

The latency-vs-authority trade-off

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

The in-process SDK is the cheapest place to make a decision — but also the easiest for an agent to avoid, because it lives inside the very process we 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 catches actions the higher layers never saw — including deliberate attempts to bypass the SDK. Authority is inverse to cost: the cheaper a layer is, the less you can trust it to be present.

What each layer catches

Layer 1 — SDK shim (in-process)

The language SDKs call into a thin native shim over aa-sdk-client, which ships events over a Unix domain socket to the runtime and applies pre-execution allow/deny via wrapper functions. It is the fastest path and gives the richest context (it sees the call before it happens), but it requires the agent to adopt the SDK and can be skipped. Its security checks are advisory only — see Trust boundaries.

Layer 2 — Sidecar proxy (aa-proxy)

The proxy terminates outbound TLS with a per-host certificate signed by a local CA generated on first start (aa-proxy/src/tls/ca.rs), inspects the decrypted request, and enforces network-egress and data policy at the wire — with no change to agent code. The interceptor returns a VerdictDecision of Forward, ForwardRedacted, Block, or AlertAndForward (aa-proxy/src/intercept/mod.rs), and for MCP tools/call it can match on arguments (aa-proxy/src/intercept/mcp.rs) — a precision the raw-bytes scanner alone cannot reach. It catches egress the SDK missed, but sees only what is routed through it.

Layer 3 — eBPF (kernel)

The kernel layer attaches uprobes to the SSL library — SSL_write (outbound plaintext) and SSL_read entry/exit (inbound plaintext) in aa-ebpf-probes/src/ssl_probes.rs — and tracepoints/kprobes for process exec and file syscalls (aa-ebpf-probes/src/exec_probes.rs, aa-ebpf/src/kprobe.rs). Because it observes at the syscall / library boundary, it sees TLS plaintext and process activity even when the agent never adopted the SDK and never routed through the proxy. It is the floor. It is Linux-only and needs elevated privileges.

How the layers 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 (aa-proto audit events), 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,
• eBPF is the floor that catches what slips past both.

Run all three and an action has nowhere to hide — an attempt to evade a higher layer simply surfaces at a lower one.

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 (union coverage)"]
        L1["Layer 1 — SDK shim<br/>aa-sdk-client · in-process · lowest latency<br/><i>advisory checks only</i>"]:::l1
        L2["Layer 2 — Sidecar proxy<br/>aa-proxy · MitM outbound HTTPS<br/>Forward / Redact / Block"]:::l2
        L3["Layer 3 — eBPF<br/>aa-ebpf · kernel SSL uprobes + syscalls<br/>highest authority"]:::l3
    end

    GW["Gateway (aa-gateway)<br/>authoritative policy · budget · decision"]:::gw
    RT["Runtime (aa-runtime)<br/>authoritative scan + redact"]:::gw
    Audit[("Tamper-evident<br/>audit trail")]

    Agent -->|"adopted SDK path"| L1
    Agent -.->|"routed HTTPS"| L2
    Agent -.->|"raw syscalls / TLS<br/>(bypass attempt)"| L3

    L1 --> RT
    L2 --> RT
    L3 --> RT
    RT -->|"unified audit wire format"| GW
    GW --> Audit

flowchart LR
    classDef catch fill:#eaf6ee,stroke:#3aa55b
    classDef miss fill:#fdecea,stroke:#d75748

    A["Agent action"] --> Q1{"SDK adopted<br/>& wired?"}
    Q1 -->|yes| C1["Caught at Layer 1<br/>(SDK)"]:::catch
    Q1 -->|"no / skipped"| Q2{"Routed<br/>through proxy?"}
    Q2 -->|yes| C2["Caught at Layer 2<br/>(proxy egress)"]:::catch
    Q2 -->|"no / direct socket"| Q3{"Linux + eBPF<br/>deployed?"}
    Q3 -->|yes| C3["Caught at Layer 3<br/>(eBPF kernel)"]:::catch
    Q3 -->|no| U["Uncovered<br/>(deploy eBPF to close)"]:::miss

The second diagram makes the composition explicit: an action only escapes governance if it evades every deployed layer. With eBPF present, the bypass path collapses to “caught at Layer 3.”

Last updated: 2026-06-11 by Chisanan232

Protection and enforcement

Once an action is observed (see Three-layer defense in depth), it must be decided on and, where necessary, blocked or scrubbed. This page covers the enforcement machinery: policy evaluation, fail-closed behavior, network-egress control, credential scanning & redaction, and budgets as a control. Every claim below is grounded in the gateway, runtime, and security crates; for the broader component picture see Architecture.

Policy evaluation

The gateway is the authoritative decision point. The policy engine (aa-gateway/src/engine/mod.rs) evaluates an AgentContext + GovernanceAction and returns a PolicyDecision — Allow, RequireApproval { reason, timeout_secs }, or Deny { reason, source_scope } (aa-gateway/src/engine/decision.rs).

Evaluation runs as a staged pipeline. The single-policy path (evaluate_primary) and the scoped-cascade path (evaluate_with_cascade) share the same stages:

Stage 6 is notable: a credential finding redacts rather than denies, so a governed action still proceeds but the secret never travels upstream. Denial is reserved for policy, egress, rate, and budget violations.

Scoped cascade and most-restrictive-wins

When scoped policies are loaded, the engine collects a cascade of PolicyDocuments along the agent’s lineage (Global → Org → Team → Agent) and merges them with most-restrictive-wins semantics (merge_decisions in aa-gateway/src/engine/decision.rs): any Deny short-circuits and wins; otherwise the narrowest-scope RequireApproval wins; only an all-Allow cascade returns Allow.

Fail-closed behavior

The system denies whenever it cannot make a safe decision. Two load-bearing examples:

• Empty policy cascade → Deny. merge_decisions returns a fail-closed Deny { reason: "no policy — fail-closed", source_scope: Global } for an empty cascade — it never silently allows (aa-gateway/src/engine/decision.rs).
• Unscannable field → redact whole. In the runtime enforcement stage, a secret-bearing field larger than max_field_bytes (default DEFAULT_MAX_FIELD_BYTES = 64 KiB) cannot be fully scanned, so it is replaced wholesale with OVERSIZED_MARKER = "[REDACTED:OVERSIZED]" rather than forwarded raw — OversizedPolicy::RedactWhole, the sole and default variant (aa-runtime/src/pipeline/enforcement.rs). The doc comment is explicit: “The runtime is a security gate, so the policy is fail-closed.”

Null-as-no-match nuance. Inside a single policy document, an unresolvable graph variable contributes nothing to the decision — a deny condition that references it does not fire (aa-gateway/src/policy/context.rs). This is a deliberate per-clause evaluation rule (fail-open on missing context within a clause), distinct from the system-level fail-closed default that governs the absence of any policy.

Network-egress control

Egress is enforced at two tiers. In the gateway, check_network_egress(host, policy) returns an EgressDecision against the policy’s allowlist (aa-gateway/src/policy/network.rs); a NetworkRequest to a host outside a non-empty allowlist is denied at Stage 2. At the wire, the proxy independently enforces egress on decrypted traffic with no agent code change (see Three-layer defense), and the eBPF SSL uprobes observe egress plaintext even when the proxy is bypassed.

Credential scanning & redaction (aa-security)

The aa-security leaf crate is the credential-detection and redaction primitive (extracted from aa-core per ADR 0002, AAASM-2567). Its CredentialScanner (aa-security/src/scanner.rs) compiles a single Aho-Corasick automaton over literal secret prefixes and patterns, mapping each match to a CredentialKind:

• LLM-provider keys (Anthropic, OpenAI),
• cloud keys (AKIA… AWS access key, GCP service account, Azure connection string),
• VCS tokens (ghp_ PAT, ghs_ app token),
• Slack tokens, database URLs (postgres, mysql, mongodb),
• private-key PEM blocks (RSA / EC / OpenSSH / generic / PGP).

A scan yields a ScanResult; redact() replaces each match with a [REDACTED:<kind>] label, and the resulting Redaction (aa-security/src/redaction.rs) stores only finding metadata — never the raw secret value.

The same crate is wired in at every trusted point:

The runtime’s RuntimeScanner holds one precompiled scanner, built once at pipeline start and reused per event — it is never rebuilt per event — and only the allowlisted secret-bearing fields of each Detail variant (ToolCall, FileOp, Process) are scanned. Variants with no free-text secret fields (LlmCall, Network, Violation, Approval) are matched explicitly with no wildcard, so adding a new detail variant fails to compile until its secret-bearing fields are triaged.

Budgets as a control

Budgets are a first-class security control against runaway spend, not merely a cost report. The gateway’s BudgetTracker (aa-gateway/src/budget/) tracks per-agent, per-team, and per-org daily/monthly spend. At Stage 7 the engine checks monthly then daily limits; on exceed it returns a Deny whose side-effect is driven by the policy’s action_on_exceed:

• ActionOnExceed::Deny — refuse the individual request, keep the agent active;
• ActionOnExceed::Suspend — attach DenyAction::SuspendAgent so the service layer suspends the agent.

The default when action_on_exceed is absent is Deny (aa-gateway/src/policy/validator.rs).

Decision flow

flowchart TD
    classDef gw fill:#e8f1ff,stroke:#5b8def
    classDef deny fill:#fdecea,stroke:#d75748
    classDef redact fill:#fff3d6,stroke:#c98a00
    classDef allow fill:#eaf6ee,stroke:#3aa55b

    A["GovernanceAction + AgentContext"]:::gw --> Casc{"Policy cascade<br/>empty?"}
    Casc -->|yes| FC["Deny — fail-closed<br/>'no policy'"]:::deny
    Casc -->|no| S1["1 Schedule"]:::gw --> S2["2 Network allowlist"]:::gw
    S2 --> S3["3 Tool allow/deny"]:::gw --> S4["4 Rate limit"]:::gw
    S4 --> S5{"5 Requires<br/>approval?"}
    S5 -->|yes| RA["RequireApproval"]:::redact
    S5 -->|no| S6["6 Credential scan<br/>(aa-security)"]:::redact
    S6 -->|finding| RED["Redact in memory<br/>[REDACTED:kind] — proceed"]:::redact
    S6 -->|clean| S7{"7 Budget<br/>exceeded?"}
    RED --> S7
    S7 -->|"yes / Deny"| BD["Deny 'budget exceeded'"]:::deny
    S7 -->|"yes / Suspend"| SUS["Deny + SuspendAgent"]:::deny
    S7 -->|no| OK["Allow"]:::allow

    S1 -.->|outside hours| D1["Deny"]:::deny
    S2 -.->|host not allowed| D2["Deny"]:::deny
    S3 -.->|tool denied| D3["Deny"]:::deny
    S4 -.->|over limit| D4["Deny"]:::deny

Last updated: 2026-06-11 by Chisanan232

Trust boundaries

The single most important decision in Agent Assembly’s Security Model is where it places trust. The answer is recorded formally in ADR 0002 — SDK Security Boundary: the SDK is not a trust boundary; the runtime and gateway are authoritative. This page explains why, and how that decision is made bypass-resistant.

Why the SDK is not a trust boundary

The fastest interception layer — the SDK — runs inside the agent’s own process, which is exactly the component the model does not trust (see the threat model). An attacker who controls the agent controls a modified, outdated, or stubbed SDK. Therefore any guarantee anchored in the SDK is not a guarantee at all: security must hold even when the SDK does nothing.

ADR 0002 audited the prior state and found enforcement in the wrong place — the only credential scan on the SDK fast-path was inside the SDK binding itself, while the trusted runtime forwarded the SDK’s payload without independently scanning it. A removed or bypassed SDK scanner would let raw secrets flow SDK → runtime → gateway. The decision reversed this:

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

Why the runtime / gateway is authoritative

The SDK event fast-path is SDK → UDS → aa-runtime → gRPC → gateway. The runtime is the mandatory chokepoint: every event must pass through it. So that is where the authoritative work lives. RuntimeScanner::enforce (aa-runtime/src/pipeline/enforcement.rs) scans, redacts, and normalizes every secret-bearing field, and the pipeline run() loop (aa-runtime/src/pipeline/mod.rs) calls it before any forward or audit, on every path — both the batched path and the immediate policy-violation path. Its doc comment states the rule directly:

Runs unconditionally — no field of the event can request that scanning be skipped, and there is no SDK trust marker on the wire.

The gateway, in turn, is the source of truth for policy (the agent cannot author its own policy) and applies a final write-boundary sanitizer before anything is persisted.

Bypass resistance — eBPF catches what the SDK and proxy miss

Trust placement answers “what if the SDK lies?” Bypass resistance answers “what if the agent skips the SDK entirely?” The three-layer model is the structural answer: a higher layer evaded simply surfaces at a lower one. An agent that skips the SDK and the proxy and links TLS directly is still observed by the eBPF SSL_write / SSL_read uprobes and exec/file syscall hooks (aa-ebpf-probes/src/ssl_probes.rs, aa-ebpf-probes/src/exec_probes.rs), because the kernel sits below anything the agent can reach.

This is verified, not asserted. The bypass-resistance suite drives the public aa_runtime::pipeline::run loop end-to-end and proves every inbound event is scanned + redacted before forward/audit on both paths, with the raw secret never leaving the runtime regardless of SDK behavior (aa-runtime/tests/aaasm_2568_gate_verification.rs). The “no trust marker” guard is partly compile-time — the exhaustive, wildcard-free match over Detail variants forces any new secret-bearing field to be triaged before it compiles.

Trust-boundary diagram

flowchart LR
    classDef untrusted fill:#fdecea,stroke:#d75748,stroke-dasharray: 4 3
    classDef trusted fill:#eaf6ee,stroke:#3aa55b
    classDef sot fill:#e8f1ff,stroke:#5b8def

    subgraph U["UNTRUSTED — agent-controllable process"]
        SDK["Python / Node / Go SDK<br/>+ aa-sdk-client shim<br/><i>advisory preflight only</i>"]:::untrusted
    end

    subgraph T["TRUSTED ENFORCEMENT"]
        RT["aa-runtime<br/>mandatory chokepoint<br/>scan · redact · normalize<br/><b>unconditional</b>"]:::trusted
        PX["aa-proxy<br/>wire egress + scan"]:::trusted
        BPF["aa-ebpf<br/>kernel uprobes / syscalls<br/>bypass floor"]:::trusted
    end

    subgraph S["SOURCE OF TRUTH"]
        GW["aa-gateway<br/>policy SoT · budget<br/>audit-write sanitizer"]:::sot
    end

    SDK -->|"UDS · no trust marker"| RT
    PX --> RT
    BPF --> RT
    RT -->|"gRPC"| GW

    %% the boundary line
    SDK -. "trust boundary" .-> RT

Everything left of the runtime is untrusted and can only advise; everything from the runtime rightward is authoritative. The dashed edge is the trust boundary itself — the SDK’s assertions stop there. See ADR 0002 for the full decision record and the boundary-first migration order that ensured SDK-side scanning was never removed before the runtime became authoritative.

Last updated: 2026-06-11 by Chisanan232

Audit and assurance

Governance is only credible if there is a trustworthy record of what happened. Agent Assembly’s audit pipeline is designed so that the trail is free of secrets, tamper-evident, and supports non-repudiation — even when an upstream sender (an SDK, a proxy, an eBPF probe) emits something it should not. This page covers the write-boundary sanitizer, redaction, and the publish path. For where audit sits in the wider system, see Architecture.

The write-boundary sanitizer

Every audit event the gateway is about to persist passes first through sanitize (aa-gateway/src/sanitizer/). The module’s own description states the principle: “The sender is the first line of defense; this module is the last.” It never trusts the inbound shape — it operates on the untyped JSON tree as received and:

• strips banned keys recursively at any depth,
• drops unknown top-level fields, counting them so a newly-emitting sender is noticed (a drift signal), and
• collapses heartbeats into a single “last seen” update on the agent row instead of writing a per-beat record.

The four classes of “never store” data are removed regardless of what any upstream emits: raw LLM prompts/completions, full tool-call payloads, eBPF packet bodies, and per-heartbeat sequence records. The BANNED_KEYS list (aa-gateway/src/sanitizer/rules.rs) is deliberately a superset — defense in depth means erring toward dropping — and includes prompt, completion, llm_input, llm_output, tool_payload, tool_response, tool_args, tool_result, packet_body, packet_payload, and heartbeat_seq.

The sanitizer returns a SanitizeOutcome — either an Audit(SanitizedAuditEvent) to persist, or a HeartbeatUpdate to fold into the agent’s “last seen” field (aa-gateway/src/sanitizer/event.rs). The SanitizedAuditEvent type is a constructor-guarded wrapper, so a value can only exist after it has been through the banned-key pass.

Redaction: secrets never reach the record

The sanitizer removes whole banned containers; the aa-security scanner removes secrets that appear inside otherwise-legitimate fields. Both run on the audit path. At the gateway audit-write boundary (aa-gateway/src/audit.rs) the CredentialScanner detects a secret and redact() replaces it with a [REDACTED:<kind>] label; the resulting Redaction (aa-security/src/redaction.rs) stores only finding metadata — kind and offset — never the raw value. Combined with the runtime’s authoritative re-scan (see Protection and enforcement), a secret is redacted before forward and again before persist, so it never lands in audit_logs.

Tamper-evidence and non-repudiation

Audit events are published off the runtime via the NATS audit publisher (aa-runtime/src/audit_publisher/). Each entry is published to a structured, tenant- and agent-scoped subject derived by subject_for (aa-runtime/src/audit_publisher/subject.rs):

assembly.audit.<tenant>.<agent>

where <tenant> is the entry’s org id (falling back to team id, then default) and <agent> is the agent id rendered as a hyphenated UUID. Scoping every record to an immutable tenant+agent identity means a record cannot be silently reattributed, and routing through a durable message bus separates the production of audit evidence (the runtime, which an agent cannot reach into) from its consumption (the gateway/storage), so the trail is not rewritable by the governed party. This separation, plus the constructor-guarded sanitized type and metadata-only redaction, is what makes the record non-repudiable: the governed action and its decision are recorded by trusted components, with no path for the agent to alter or suppress its own history.

End-to-end audit data flow

flowchart TD
    classDef src fill:#eef2ff,stroke:#6366f1
    classDef trusted fill:#eaf6ee,stroke:#3aa55b
    classDef guard fill:#fff3d6,stroke:#c98a00
    classDef store fill:#e8f1ff,stroke:#5b8def

    SDK["SDK (advisory)"]:::src
    PX["aa-proxy"]:::src
    BPF["aa-ebpf"]:::src

    RT["aa-runtime pipeline<br/>RuntimeScanner::enforce<br/>scan · redact · normalize<br/><b>unconditional</b>"]:::trusted
    PUB["audit_publisher<br/>subject assembly.audit.&lt;tenant&gt;.&lt;agent&gt;"]:::trusted
    BUS[["NATS bus<br/>(durable, append-oriented)"]]:::trusted

    SAN["Gateway sanitizer<br/>strip BANNED_KEYS (recursive)<br/>drop unknown top-level (counted)<br/>collapse heartbeats"]:::guard
    RED["aa-security redaction<br/>[REDACTED:kind] · metadata only"]:::guard

    HB["agents.last_heartbeat<br/>update"]:::store
    LOG[("audit_logs<br/>secret-free, attributed")]:::store

    SDK --> RT
    PX --> RT
    BPF --> RT
    RT --> PUB --> BUS --> SAN
    SAN -->|"Audit(SanitizedAuditEvent)"| RED --> LOG
    SAN -->|"HeartbeatUpdate"| HB

The record that reaches audit_logs has passed an authoritative redaction in the runtime, a recursive banned-key strip in the sanitizer, and a final metadata-only credential redaction — and is bound to an immutable tenant+agent subject. No single compromised or careless sender can defeat the trail.

Last updated: 2026-06-11 by Chisanan232

Architecture

This chapter is the engineering map of agent-assembly — the open-source core that governs AI agents by intercepting their actions at three independent layers and routing every action through one central gateway.

It is written for contributors and integrators who want to understand how the system is built, not just how to operate it. For the system-level overview, see System architecture; for the security rationale, see the Security Model.

Pages in this chapter

• System architecture — the big picture: the 28 workspace crates, the three interception layers, the gateway / API / runtime / storage split, and the gRPC / HTTP / UDS transport topology, with a mermaid system diagram.
• Component deep-dives — a per-crate tour of responsibilities, key types, and dependencies: gateway, policy engine, budgets, runtime, the three interception crates, API, CLI, foundation crates, storage, and cache.
• Key workflows — policy evaluation, agent registration, budget tracking & rollup, and the interception/enforcement path, each as a mermaid sequence or flow diagram grounded in the real code path.
• Data flows — how an intercepted event travels from a layer through the gateway, the policy engine, and the write-boundary sanitizer into durable, tamper-evident storage.
• Building & contributing — build, test, and lint basics for working on the workspace.

The model in one diagram

flowchart LR
    Agent[AI agent] --> Layers["3 interception layers<br/>SDK · proxy · eBPF"]
    Layers --> RT["aa-runtime<br/>chokepoint"]
    RT -->|gRPC :50051| GW["aa-gateway<br/>policy · budget · audit"]
    GW --> Store[("storage")]
    GW --> API["aa-api<br/>HTTP :7700"]
    API --> Dash["dashboard / tooling"]

Start with System architecture.

System architecture

This page is the big-picture map of agent-assembly: the workspace crates, how the three interception layers feed one central gateway, and which transport each component speaks. Read it first; the component deep-dives, key workflows, and data flows pages zoom into each piece.

For the trust-boundary view of the same system — what each layer is trusted to do and where the authoritative checks live — see the Security Model.

The one-sentence model

Agents act; the three interception layers observe those actions and forward them to the gateway; the gateway evaluates policy, tracks budgets, and writes an audit record before returning allow or deny.

The gateway is the single decision-maker. The interception layers differ only in where they sit and how much they can bypass — they all converge on the same protobuf wire format defined in aa-proto and the same PolicyService RPC.

Workspace at a glance

The Cargo workspace declares 28 member crates in the top-level Cargo.toml. They group into a handful of architectural roles:

Two further eBPF crates — aa-ebpf-probes and aa-ebpf-programs — live alongside the workspace but are intentionally out of workspace: they compile for the bpfel-unknown-none BPF target and are built by aa-ebpf’s build.rs via aya-build, so they cannot be selected with cargo -p.

The per-language SDK shims (Python / Node / Go) do not live in this monorepo. They wrap aa-sdk-client and consume it via a pinned git SHA from the sibling python-sdk / node-sdk / go-sdk repositories.

Crate / component map

The diagram highlights the core architectural crates; storage drivers, dev-tool adapters, and test harnesses are folded into summary nodes for clarity. Edges follow real path dependencies in each crate’s Cargo.toml.

graph TD
    classDef foundation fill:#e8f1ff,stroke:#5b8def
    classDef storage fill:#eef6ff,stroke:#5b8def
    classDef ebpf fill:#fdecea,stroke:#d75748
    classDef ffi fill:#eaf6ee,stroke:#3aa55b
    classDef control fill:#fff3d6,stroke:#c98a00
    classDef outOfWorkspace fill:#fdecea,stroke:#d75748,stroke-dasharray: 5 3

    %% Foundation
    aa_proto[aa-proto<br/><i>wire schema</i>]:::foundation
    aa_core[aa-core<br/><i>domain types</i>]:::foundation
    aa_security[aa-security<br/><i>scanner / redaction</i>]:::foundation

    %% Storage
    aa_storage[aa-storage<br/><i>trait facade</i>]:::storage
    aa_cache[aa-cache<br/><i>L1 cache</i>]:::storage
    storage_drivers["aa-storage-{memory,postgres,<br/>redis,sqlite-buffer}"]:::storage

    %% Interception / runtime
    aa_runtime[aa-runtime<br/><i>per-agent chokepoint</i>]:::ffi
    aa_sdk_client[aa-sdk-client<br/><i>FFI-agnostic client</i>]:::ffi
    aa_wasm[aa-wasm]:::ffi
    aa_sandbox[aa-sandbox<br/><i>WASI tool sandbox</i>]:::ffi
    aa_proxy[aa-proxy<br/><i>L2 sidecar</i>]:::ebpf
    aa_ebpf[aa-ebpf<br/><i>L3 kernel</i>]:::ebpf
    aa_ebpf_common[aa-ebpf-common]:::ebpf
    aa_probes["aa-ebpf-probes /<br/>aa-ebpf-programs<br/><i>out-of-workspace BPF</i>"]:::outOfWorkspace

    %% Control plane
    aa_gateway[aa-gateway<br/><i>gRPC 50051</i>]:::control
    aa_api[aa-api<br/><i>HTTP / OpenAPI</i>]:::control
    aa_cli[aa-cli<br/><i>aasm</i>]:::control

    aa_core --> aa_security
    aa_storage --> aa_core
    aa_cache --> aa_core
    storage_drivers --> aa_storage

    aa_runtime --> aa_core
    aa_runtime --> aa_proto
    aa_runtime --> aa_ebpf
    aa_sdk_client --> aa_proto
    aa_sdk_client -. preflight .-> aa_security
    aa_wasm --> aa_core

    aa_ebpf --> aa_core
    aa_ebpf --> aa_ebpf_common
    aa_probes --> aa_ebpf_common

    aa_proxy --> aa_core
    aa_proxy --> aa_proto
    aa_proxy --> aa_runtime
    aa_proxy --> aa_sandbox

    aa_gateway --> aa_core
    aa_gateway --> aa_proto
    aa_gateway --> aa_runtime
    aa_gateway --> aa_storage
    aa_gateway --> aa_cache
    aa_api --> aa_core
    aa_api --> aa_gateway
    aa_api --> aa_runtime
    aa_cli --> aa_core
    aa_cli --> aa_gateway

aa-core and aa-proto are the two foundation leaves everything else builds on: aa-core holds the Rust domain model and the storage traits, aa-proto holds the protobuf schema that crosses every process boundary.

How the layers, gateway, API, runtime, and storage fit together

flowchart TB
    subgraph agent_host["Agent host"]
        Agent[AI agent process]
        subgraph layers["Three interception layers"]
            L1["L1 — In-process SDK<br/>(aa-sdk-client shims, aa-wasm)"]
            L2["L2 — Sidecar proxy<br/>(aa-proxy)"]
            L3["L3 — eBPF<br/>(aa-ebpf, kernel)"]
        end
        RT["aa-runtime<br/>per-agent chokepoint"]
    end

    subgraph control["Control plane"]
        GW["aa-gateway<br/>registry · policy · budget · audit"]
        API["aa-api<br/>HTTP / OpenAPI read API"]
    end

    subgraph persistence["Storage"]
        STORE[("aa-storage drivers<br/>memory / postgres / redis / sqlite-buffer")]
    end

    Dash["Dashboard / operators"]
    CLI["aasm CLI"]

    Agent --> L1 & L2 & L3
    L1 -->|UDS IpcFrame| RT
    L2 -->|forward| RT
    L3 -->|ring buffer| RT
    RT -->|gRPC PolicyService.CheckAction<br/>:50051| GW
    GW --> STORE
    API --> GW
    Dash -->|HTTP / WS| API
    CLI -->|gRPC| GW

• The interception layers are deployment-independent: a deployment can run any subset (SDK only, SDK + proxy, all three). Each layer turns an agent action into an event in the aa-proto schema.
• aa-runtime is the per-agent chokepoint. Because the SDK is untrusted, the runtime re-scans every event (the enforcement stage in aa-runtime/src/pipeline/enforcement.rs) before forwarding it.
• aa-gateway is the brain. It hosts the agent registry, the policy engine, per-team budgets, and the audit pipeline, and it serves gRPC on :50051.
• aa-api depends on aa-gateway in-process and re-exposes its read surfaces over HTTP with an OpenAPI schema (via utoipa) for the dashboard and tooling.
• Storage is a pluggable trait facade (aa-storage) with swappable drivers, fronted by an in-process L1 cache (aa-cache).

Transport topology

Every cross-process message rides one of three transports. All gRPC and Unix-socket payloads share the aa-proto schema.

flowchart LR
    SDK["SDK shim<br/>(aa-sdk-client)"] -- "UDS IpcFrame" --> RT["aa-runtime"]
    RT -- "gRPC :50051" --> GW["aa-gateway"]
    PROXY["aa-proxy"] -- "gRPC :50051" --> GW
    EBPF["aa-ebpf"] -- "ring buffer → events" --> RT
    GW -- "in-process dep" --> API["aa-api"]
    DASH["Dashboard"] -- "HTTP / OpenAPI :7700" --> API
    CLI["aasm CLI"] -- "gRPC :50051" --> GW

The seven gRPC services are registered together in aa-gateway/src/server.rs; the gateway can serve them over either TCP (serve_tcp) or a Unix socket (serve_uds). The default gRPC listen address is 127.0.0.1:50051; the HTTP API default bind is 127.0.0.1:7700 (constant DEFAULT_ADDR in aa-api/src/config.rs, overridable via AA_API_ADDR).

Where to go next

• Component deep-dives — per-crate responsibilities, key types, and dependencies.
• Key workflows — policy evaluation, agent registration, budget rollup, and the enforcement path as sequence diagrams.
• Data flows — how an intercepted event travels from a layer through the gateway to the audit log and storage.
• Security Model — the same system viewed through trust boundaries and defense-in-depth.

Last updated: 2026-06-11 by Chisanan232

Component deep-dives

This page walks the major crates one by one: what each owns, its key types, and who it depends on. For the bird’s-eye map and the dependency diagram, start with System architecture.

All paths link into the master tree on GitHub.

aa-gateway — the governance brain

aa-gateway is the central decision-maker. It hosts the agent registry, the policy engine, per-team budgets, the audit pipeline, approvals, anomaly detection, and the seven gRPC services. Its module tree is large; the load-bearing sub-modules are:

Key types: AgentRecord, AgentRegistry, AgentStatus (registry/store.rs). Depends on: aa-core, aa-proto, aa-runtime, aa-storage, aa-cache. Serves: gRPC on 127.0.0.1:50051.

The policy engine (aa-gateway/src/policy/)

The engine turns a YAML/TOML policy bundle into a decision. Entry point is validator::PolicyValidator::from_yaml.

The evaluation flow is detailed on the Key workflows page.

Budgets (aa-gateway/src/budget/)

A request that would breach a budget downgrades from allow to deny. See budget tracking & rollup.

aa-runtime — the per-agent chokepoint

aa-runtime sits between an agent’s interception layers and the gateway. It is the mandatory chokepoint on the SDK fast-path (SDK → UDS → runtime → gateway). Because the SDK is untrusted, the runtime re-scans every event before forwarding.

Key types: LayerSet, EnforcementConfig, PipelineEvent, EnrichedEvent. Depends on: aa-core, aa-proto, aa-ebpf.

The three interception layers

L1 — In-process SDK: aa-sdk-client (+ aa-wasm)

aa-sdk-client is the FFI-agnostic SDK runtime client. The per-language shims (Python / Node / Go, in their own repos) are thin wrappers over it.

aa-wasm is a separate in-workspace target compiling governance components to WebAssembly (via wasm-bindgen) for browser / edge agents without a native sidecar.

Trust note: the SDK is not a security boundary — anything it asserts is re-verified by aa-runtime. See trust boundaries.

L2 — Sidecar proxy: aa-proxy

Intercepts outbound HTTPS via MitM with a per-host CA, enforcing network-egress policy without code changes.

Depends on: aa-core, aa-proto, aa-runtime, aa-sandbox.

L3 — eBPF: aa-ebpf (+ aa-ebpf-common, out-of-workspace probes)

Kernel hooks watching SSL libraries (uprobes) and process exec / file syscalls. Linux-only, lowest bypass risk.

aa-ebpf-common holds types shared between userspace and the BPF programs. aa-ebpf-probes / aa-ebpf-programs are the out-of-workspace BPF-target crates built by aa-ebpf/build.rs via aya-build.

Depends on: aa-core, aa-ebpf-common.

aa-api — the HTTP / OpenAPI read API

aa-api depends on aa-gateway in-process and re-exposes its read surfaces over HTTP (Axum) with an OpenAPI schema (utoipa). It is the dashboard’s backend.

Depends on: aa-core, aa-gateway, aa-runtime.

aa-cli — the aasm operator front-end

aa-cli ships the aasm binary. It talks gRPC to the gateway and HTTP to the API. Common subcommands: aasm status, aasm topology, aasm policy, aasm agent, aasm cost, aasm audit, aasm dashboard (TUI). The full surface is documented in the CLI Reference.

Depends on: aa-core, aa-gateway.

Foundation crates

aa-core — domain model + storage traits

The leaf everything builds on. Holds the Rust domain types and the storage trait contracts (std-gated).

aa-proto — the wire schema

Protobuf definitions (under proto/, package prefix assembly.*.v1) compiled with prost / tonic. Defines the seven gRPC services and all wire messages. Every cross-process payload — gRPC and UDS alike — uses these types.

aa-security — credential scanner + redaction

A small leaf crate (only aho-corasick + serde) holding CredentialScanner, CredentialFinding, and Redaction. Extracted out of aa-core so both the runtime enforcement stage and the SDK preflight can depend on it without pulling in the full core.

Storage & cache

aa-storage — trait facade + driver registry

aa-storage re-exports the aa_core::storage traits and adds the runtime driver registry: StorageConfig, a Registry, factory traits, ConfigError, and register_builtin_drivers (memory / redis / postgres). It is the loader the CLI’s aasm config validate / aasm config boot exercise.

Storage drivers

Each driver implements the aa-core storage traits and is verified against the shared conformance harness.

aa-cache — in-process L1 cache

L1Cache<S: CacheSource> — a DashMap-backed, TTL’d, cache-aside wrapper over any store. Concurrent misses for the same key collapse to a single backend load (stampede protection). The gateway fronts its policy store with this cache.

WASM tool sandbox: aa-sandbox

aa-sandbox hosts a wasmtime-based runtime that executes WASM-marked tools. It enforces three isolation surfaces — filesystem allowlist (WASI preopened dirs), CPU budget (wasmtime instruction fuel), and memory ceiling (Store limiter) — each surfaced as a deterministic SandboxError. It is consumed by aa-proxy via the tool-dispatch surface.

Test / conformance crates

• conformance — the cross-crate trait conformance harness; every storage driver runs the same suite.
• aa-integration-tests — end-to-end tests that wire multiple crates together (kept separate to avoid dependency cycles).

Last updated: 2026-06-11 by Chisanan232

Key workflows

This page traces the four workflows that define agent-assembly’s runtime behaviour, each grounded in the real code path:

• Policy evaluation
• Agent registration
• Budget tracking & rollup
• Interception & enforcement

For component-level detail behind each box, see Component deep-dives; for the bird’s-eye map, see System architecture.

Policy evaluation

When aa-gateway receives a PolicyService.CheckAction RPC, the policy engine under aa-gateway/src/policy/ walks parse → compile → scope cascade → budget → decision, then audits the result. The decision type (engine/decision.rs) is one of Allow, Deny, or RequireApproval.

flowchart TD
    Req["CheckActionRequest<br/>(action, target, labels)"] --> Cache{Decision<br/>cache hit?<br/>engine/cache.rs}
    Cache -->|hit| Resp
    Cache -->|miss| Parse["policy/raw.rs<br/>deserialise bundle"]
    Parse --> Validate["policy/validator.rs<br/>structural validation"]
    Validate --> Compile["policy/expr.rs<br/>compile predicates"]
    Compile --> Cascade["policy/document.rs + scope.rs<br/>org → team → agent → tool<br/>most-restrictive-wins"]
    Cascade --> Budget["budget/tracker.rs<br/>check team budget"]
    Budget --> Decide{PolicyDecision}
    Decide -->|Allow| Audit
    Decide -->|Deny| Audit
    Decide -->|RequireApproval| Approval["approval queue<br/>(timeout ⇒ Pending)"]
    Approval --> Audit
    Audit["audit.rs<br/>append hash-chained entry"] --> Resp["CheckActionResponse"]

1. Decision cache — engine/cache.rs short-circuits repeat lookups for the same (scope, action) key.
2. Parse + validate — policy/raw.rs deserialises the active bundle; policy/validator.rs enforces structural invariants (well-formed scopes, unique rule names).
3. Compile — policy/expr.rs turns rule predicates into a typed expression tree evaluated against the request’s ActionType, target, and labels.
4. Scope cascade — policy/document.rs + scope.rs walk org → team → agent → tool and merge most-restrictive-wins, with cycle detection on delegation.
5. Budget check — budget/tracker.rs (priced via budget/pricing.rs) downgrades an otherwise-allowed request to Deny if it would breach a budget.
6. Decision — engine/decision.rs yields Allow, Deny { reason }, or RequireApproval { timeout_secs }.
7. Audit — every decision is appended to the hash-chained audit log via audit.rs before the response is returned.

Latency targets and current p99 measurements live in Benchmarks — Policy Check p99.

Agent registration

Registration flows through AgentLifecycleService.Register (aa-gateway/src/service/lifecycle_service.rs), which validates delegation depth and writes into the DashMap-backed AgentRegistry. Agents then keep their record live with periodic Heartbeats.

sequenceDiagram
    autonumber
    participant Agent
    participant RT as aa-runtime
    participant LS as AgentLifecycleService<br/>(aa-gateway)
    participant Reg as AgentRegistry<br/>(registry/store.rs)
    participant Store as Storage<br/>(storage_bridge.rs)

    Agent->>RT: start with agent identity + parent
    RT->>LS: gRPC Register(RegisterRequest)
    LS->>LS: validate delegation depth<br/>(≤ DEFAULT_MAX_AGENT_DEPTH = 10)
    alt depth OK and not already registered
        LS->>Reg: insert AgentRecord (status Active)
        Reg->>Store: persist via storage bridge
        LS-->>RT: RegisterResponse (token)
    else already registered / depth exceeded
        LS-->>RT: AlreadyExists / FailedPrecondition
    end

    loop heartbeat interval
        RT->>LS: Heartbeat(HeartbeatRequest)
        LS->>Reg: refresh last-seen, recent events
        LS-->>RT: HeartbeatResponse (control commands?)
    end

• Delegation depth — a sub-agent’s depth must not exceed DEFAULT_MAX_AGENT_DEPTH (10); over-deep registrations are rejected.
• Lineage — the registry records parent/child links (registry/lineage.rs) so the topology tree and orphan handling (registry/orphan.rs) work.
• Control stream — ControlStream lets the gateway push commands (e.g. SuspendCommand) back to a live agent.
• Deregister — on shutdown the agent calls Deregister; orphaned children are handled per the configured OrphanMode.

Budget tracking & rollup

Every priced action updates the in-memory BudgetTracker; the dashboard, SDK, and CLI read a composed BudgetRollup across agent / team / org / subtree scopes.

flowchart LR
    subgraph track["Tracking (write path)"]
        Action["priced action<br/>(model + tokens)"] --> Price["budget/pricing.rs<br/>PricingTable"]
        Price --> Tracker["budget/tracker.rs<br/>BudgetTracker"]
        Tracker --> Windows["daily + monthly windows<br/>per agent / team / global"]
        Windows --> Alert{"≥ 80% / 95%?"}
        Alert -->|yes| Broadcast["BudgetAlert<br/>(broadcast channel)"]
    end

    subgraph roll["Rollup (read path)"]
        Req["GET /agents/{id}/budget<br/>or aasm policy show --show-budget"] --> Rollup["budget/rollup.rs<br/>BudgetRollup"]
        Rollup --> Rows["BudgetRow[]<br/>agent · team · org · subtree"]
    end

    Tracker -. read-only accessors .-> Rollup

• Pricing — budget/pricing.rs converts model + token counts into a USD cost.
• Windows — BudgetTracker keeps daily and monthly windows for each agent, each team, and the global total.
• Alerts — crossing 80 % or 95 % of a limit emits a BudgetAlert on a broadcast channel (capacity 64) for live dashboards.
• Rollup — budget/rollup.rs composes a BudgetRow per scope (agent, team:<id>, org, subtree) using the tracker’s read-only accessors — narrowest scope first. The same rollup drives both the HTTP endpoint and aasm policy show <agent_id> --show-budget.

Interception & enforcement

An agent action is observed by one of the three layers, normalised into the aa-proto wire format, re-scanned by aa-runtime, then sent to the gateway for a decision. The runtime is the mandatory chokepoint: it never trusts the SDK’s assertions.

sequenceDiagram
    autonumber
    participant Agent
    participant SDK as L1 SDK shim<br/>(aa-sdk-client)
    participant Proxy as L2 proxy<br/>(aa-proxy)
    participant eBPF as L3 eBPF<br/>(aa-ebpf)
    participant RT as aa-runtime<br/>pipeline + enforcement
    participant GW as aa-gateway<br/>PolicyService

    alt L1 — in-process
        Agent->>SDK: tool / LLM / network call
        SDK->>RT: UDS IpcFrame (event)
    else L2 — sidecar
        Agent->>Proxy: outbound HTTPS (MitM)
        Proxy->>RT: forwarded event
    else L3 — kernel
        Agent-->>eBPF: SSL_write / exec / file syscall
        eBPF->>RT: ring-buffer event
    end

    RT->>RT: enrich (pipeline/event.rs)
    RT->>RT: scan + redact (pipeline/enforcement.rs)<br/>fail-closed, oversized ⇒ redact whole
    RT->>GW: CheckAction(CheckActionRequest)
    GW-->>RT: Allow / Deny / RequireApproval
    alt Allow
        RT-->>Agent: pass-through
    else Deny
        RT-->>Agent: error / blocked
    else RequireApproval
        RT->>RT: approval_sink.wait_for_approval<br/>(timeout ⇒ Decision::Pending)
        RT-->>Agent: allow or block on resolution
    end

Key invariants from aa-runtime/src/pipeline/enforcement.rs:

• The runtime re-scans every event unconditionally — there is no already_scanned / clean wire marker, and none is honoured.
• Enforcement is fail-closed: a field larger than max_field_bytes (default 64 KiB) cannot be fully scanned, so it is redacted whole ([REDACTED:OVERSIZED]) rather than partially forwarded.
• The credential scanner / redaction primitives come from the aa-security leaf crate.

The eBPF layer is observe-and-forward for bypass-detection: it cannot block in-kernel, so it streams audit events while the SDK and proxy layers carry the synchronous allow/deny. For the trust rationale, see three-layer defense.

Where each event goes next

Once a decision is made, the event flows into the audit and storage pipeline — covered in detail on the Data flows page.

Last updated: 2026-06-11 by Chisanan232

Data flows

This page follows the data — not the control decisions — through the system: how an intercepted event becomes a decision, then a durable, tamper-evident audit record. For the decision logic itself, see Key workflows; for the trust view, see the Security Model.

End-to-end: layer → gateway → policy → audit → storage

flowchart TD
    subgraph layers["Interception layers"]
        L1["L1 SDK<br/>(aa-sdk-client)"]
        L2["L2 proxy<br/>(aa-proxy)"]
        L3["L3 eBPF<br/>(aa-ebpf)"]
    end

    subgraph runtime["aa-runtime"]
        IPC["ipc/ — UDS IpcFrame"]
        PIPE["pipeline — enrich + batch"]
        ENF["enforcement — scan + redact<br/>(fail-closed)"]
        PUB["audit_publisher — NATS"]
    end

    subgraph gateway["aa-gateway"]
        POL["PolicyService.CheckAction"]
        AW["AuditWriter (audit.rs)<br/>append-only JSONL"]
        SAN["sanitizer/ — sanitize()<br/>drop 'never store' data"]
        CONS["audit_consumer.rs<br/>JetStream pull-consumer"]
    end

    NATS[("NATS JetStream<br/>assembly.audit.>")]
    JSONL[("per-session JSONL<br/>tamper-evident")]
    PG[("aa-storage-postgres<br/>audit_logs")]

    L1 -->|IpcFrame| IPC
    L2 -->|event| IPC
    L3 -->|ring buffer| IPC
    IPC --> PIPE --> ENF
    ENF --> POL
    ENF --> PUB
    POL -->|decision| AW
    AW --> JSONL
    AW -. dual sink .-> PG
    PUB -->|publish| NATS
    NATS --> CONS
    CONS --> SAN --> PG

There are two paths an audit record can take, and the design is deliberately layered so neither is a single point of failure:

1. Synchronous decision audit (in-gateway). Every CheckAction decision is appended by AuditWriter (aa-gateway/src/audit.rs) as one JSON line to a per-session JSONL file. The JSONL file is the tamper-evident primary record (hash-chained AuditEntry). When a durable StorageBackend is configured, the writer follows each JSONL append with storage.append_audit_event(...) (the dual-sink path); a storage failure is logged but never stops the pipeline, and a restart can replay missed entries from the JSONL file.
2. Asynchronous event stream (via NATS). aa-runtime’s audit_publisher publishes audit records to the NATS subject assembly.audit.<tenant>.<agent> and returns control to the agent immediately (fire-and-forget). The gateway’s audit_consumer is a durable JetStream pull-consumer over assembly.audit.> that batches, sanitises, and persists to Postgres.

The audit write path in detail

sequenceDiagram
    autonumber
    participant RT as aa-runtime<br/>audit_publisher
    participant NATS as NATS JetStream<br/>assembly.audit.>
    participant Cons as audit_consumer.rs<br/>(producer task)
    participant Chan as bounded mpsc
    participant Writer as audit_consumer.rs<br/>(DB-writer task)
    participant San as sanitizer::sanitize
    participant PG as audit_logs<br/>(Postgres)

    RT->>NATS: publish AuditEvent (fire-and-forget)
    NATS->>Cons: deliver (pull-consumer, AckPolicy::All)
    Cons->>Chan: send().await (backpressure, never drop)
    Chan->>Writer: drain up to batch_size
    loop per batch
        Writer->>San: sanitize(RawAuditEvent)
        San-->>Writer: SanitizedAuditEvent / HeartbeatUpdate
        Writer->>PG: multi-row INSERT … ON CONFLICT (event_id) DO NOTHING
        Writer->>NATS: ack last message (acks whole batch)
    end

Properties enforced by aa-gateway/src/audit_consumer.rs:

• Batching — the writer drains the channel into batches and writes each with a single multi-row INSERT, one DB round-trip and one ack per batch.
• Idempotency — each event becomes an AuditLogRecord keyed by its own event_id; ON CONFLICT (event_id) DO NOTHING dedupes retries and intra-batch repeats (bumping aa_audit_duplicates_total).
• At-least-once — AckPolicy::All acks the batch’s last message only after the whole batch persists; a failed batch is left un-acked so NATS redelivers after ack_wait.
• Backpressure — the channel is bounded; a full channel makes the producer await room rather than drop, so bursts queue durably in JetStream (aa_audit_consumer_channel_depth exposes the in-flight depth).

The write-boundary sanitizer

Before anything reaches audit_logs, the consumer runs the write-boundary sanitize() pass (aa-gateway/src/sanitizer/). The sanitizer is the last line of defense and never trusts the inbound shape — it operates on the untyped JSON tree as received:

flowchart LR
    Raw["RawAuditEvent<br/>(untyped JSON)"] --> Strip["strip banned keys<br/>recursively"]
    Strip --> Drop["drop unknown top-level fields<br/>(count them as a metric)"]
    Drop --> Beat{"heartbeat?"}
    Beat -->|yes| Collapse["collapse into<br/>HeartbeatUpdate<br/>(last-seen, not per-beat)"]
    Beat -->|no| Out["SanitizedAuditEvent"]
    Collapse --> Out

Four classes of “never store” data are dropped at this boundary regardless of what an upstream SDK or proxy emitted: raw LLM prompts / completions, full tool-call payloads, eBPF packet bodies, and per-heartbeat sequence records. Counting unknown fields means a newly-emitting sender is noticed rather than silently persisted.

Two-layer defense: the sender (runtime enforcement) is the first line — it scans and redacts before forwarding; the sanitizer is the last line — it strips before persisting. Neither trusts the other. See trust boundaries.

Storage data flow

The gateway never talks to a concrete database directly — it goes through the aa-storage trait facade, and the active driver decides where bytes land.

flowchart TD
    GW["aa-gateway"] --> Facade["aa-storage<br/>trait facade + Registry"]
    Facade --> Cache["aa-cache<br/>L1Cache (cache-aside, TTL)"]
    Cache --> Driver{"active driver"}
    Driver --> Mem[("aa-storage-memory<br/>DashMap")]
    Driver --> PG[("aa-storage-postgres<br/>sqlx")]
    Driver --> Redis[("aa-storage-redis<br/>deadpool")]
    Driver --> SQLite[("aa-storage-sqlite-buffer<br/>local write-buffer")]

• L1 cache. Read-heavy stores (e.g. the policy store) are fronted by aa-cache::L1Cache, a DashMap-backed cache-aside layer with TTL and stampede protection — concurrent misses for the same key collapse to one backend load.
• Driver selection. aa-storage’s Registry + register_builtin_drivers resolves the configured backend at boot; aasm config validate and aasm config boot exercise this loader.
• Audit storage shape. audit_entry_to_storage_event (aa-gateway/src/storage/audit_bridge.rs) maps a hash-chained AuditEntry into the storage AuditEvent keyed by event_id; the Postgres driver writes it as a metadata-only audit_logs row (no raw payloads — those were already dropped by the sanitizer).

Summary of the data’s journey

Last updated: 2026-06-11 by Chisanan232

Building & contributing

This page is the short version of building, testing, and linting the workspace. The authoritative source is CONTRIBUTING.md at the repo root; read it before opening a pull request.

Prerequisites

• Rust stable (≥ 1.75) — install via rustup.
• cargo-nextest — cargo install cargo-nextest (the test runner).
• cargo-deny — cargo install cargo-deny (license / advisory checks).
• Lefthook — brew install lefthook (macOS) or see the Lefthook install guide. The hook configuration lives in lefthook.toml.

Setup

git clone https://github.com/ai-agent-assembly/agent-assembly.git
cd agent-assembly

# Install git hooks (fmt, clippy, deny on commit; doc on push)
lefthook install

# Verify the workspace builds
cargo build --workspace

# Run the full test suite
cargo nextest run --workspace

Common commands

Notes:

• eBPF crates (aa-ebpf*) compile with target-specific toolchains; cargo check -p aa-ebpf is sufficient on non-Linux environments. The out-of-workspace BPF crates (aa-ebpf-probes, aa-ebpf-programs) are built by aa-ebpf/build.rs via aya-build and cannot be selected with cargo -p.
• The CLI binary is aasm (shipped by aa-cli); smoke-test it with ./target/debug/aasm <subcommand>.

Faster builds (optional)

The dev profile already builds dependencies at opt-level = 1 with line-tables-only debuginfo, so warm rebuilds link faster while backtraces stay readable — no setup needed. A faster linker is opt-in: install it and uncomment the block for your platform in .cargo/config.toml (mold + clang on Linux, lld via brew install llvm on macOS).

Commit & branch conventions

• Branches: <version>/<ticket-number>/<short-summary>, e.g. v0.0.1/AAASM-42/add_agent_registry.
• Commits: Gitmoji-prefixed, <emoji> (<scope>): <imperative summary>, one logical unit per commit, bisectable. Example: ✨ (aa-core): Add AgentId newtype wrapper.

Adding a new crate

1. cargo new --lib aa-<name> from the repo root.
2. Add aa-<name> to the members array in the top-level Cargo.toml.
3. Inherit workspace metadata (version.workspace = true, etc.) and use the shared [workspace.lints.clippy] rather than redefining clippy lints per-crate.

Last updated: 2026-06-11 by Chisanan232

API reference

Build and browse the Rust API docs locally. The authoritative reference lives in rustdoc, generated directly from source — there is no hand-written API doc to drift out of date. Generate the whole workspace and open it in one command:

cargo doc --workspace --no-deps --open

The rest of this chapter covers the flags that matter and maps each crate to its rustdoc entry point.

Generating rustdoc locally

The whole-workspace rustdoc is built with cargo doc. The pre-push lefthook hook also runs this command, so the docs are guaranteed to compile on master.

# Build rustdoc for every workspace member without recursing into transitive deps.
cargo doc --workspace --no-deps

# Same, but also opens the index page in the default browser.
cargo doc --workspace --no-deps --open

# Document private items too — useful when working inside a single crate.
cargo doc -p aa-gateway --no-deps --document-private-items --open

The HTML output lands in target/doc/. Open target/doc/aa_core/index.html (or any other crate’s index) directly if you’d rather not use --open.

Note on eBPF crates — aa-ebpf* requires a nightly toolchain to build the BPF target. CI excludes these crates from the standard build matrix and validates them in a dedicated job. For rustdoc on macOS or non-Linux machines, run cargo doc --workspace --no-deps --exclude aa-ebpf to skip them.

Per-crate API surface

Once rustdoc is built (target/doc/<crate>/index.html), the most-frequented entry points are:

The HTTP API (served by aa-api) additionally publishes a generated OpenAPI v1 spec. Validate the spec with npx @stoplight/spectral-cli lint openapi/v1.yaml.

Hosted documentation (deferred)

Publishing rustdoc to docs.rs and the mdBook to GitHub Pages is out of scope for v0.0.1. Both are tracked as follow-up Stories under Epic AAASM-13. Until then, run cargo doc --workspace --no-deps --open and mdbook serve docs --open locally.

Last updated: 2026-06-11 by Chisanan232

Version Compatibility Matrix

This document tracks which versions of aa-runtime are compatible with each SDK version. Update this file whenever any component version changes — see CI enforcement below.

CI enforcement for SDK version changes is pending cross-repo CI integration. Until then, SDK version bumps must be accompanied by a manual update to this file.

Compatibility Matrix

Legend:

• ✓ Compatible — fully supported
• ⚠️ Partial — works with known limitations (see notes)
• ✗ Incompatible — do not use together

Minimum Supported Runtime Version per SDK

Supported Protocol Versions per Runtime

A runtime version may support multiple protocol versions to allow SDK upgrades without simultaneous runtime upgrades.

Dual-URL SDK configuration

Starting with the v0.0.1 SDK line, every SDK accepts two endpoint fields so a single install can target either a single-host OSS deployment or a split enterprise deployment (gRPC gateway and HTTP control plane on different hosts).

The HTTP control plane serves agent registration, policy checks, and topology edges (POST /agents/{id}/register, POST /agents/{id}/policy/check, POST /topology/edges). The gRPC transport carries the streaming op-control, lifecycle, audit, and approval flows and always reads gateway_url.

Backwards-compatible default

control_plane_url is optional. When it is not set, each SDK defaults it to the resolved gateway_url, so a single-host OSS dev install keeps working with only one endpoint configured — the pre-feature behaviour is preserved exactly. It only needs a distinct value when the HTTP control plane and the gRPC gateway live on separate hosts (the production enterprise topology).

Resolution order and environment variables

Each field resolves as explicit init argument > environment variable > unset:

If control_plane_url is still unset after this chain, it falls back to gateway_url as described above.

Canonical AA_* prefix and the deprecated AAASM_* alias

AA_* is the canonical environment-variable prefix across all SDKs — AA_GATEWAY_URL, AA_CONTROL_PLANE_URL, and AA_API_KEY. New configuration should always use this prefix.

The legacy AAASM_* prefix — used by the older zero-config gateway resolver in each SDK — is a deprecated alias. It is still honoured for backwards-compatibility, but reading a value from an AAASM_* variable emits a deprecation warning, and the alias will be removed in a future major version. Migrate to the AA_* names.

This prefix reconciliation is tracked across the SDKs under AAASM-3019; sibling subtasks update the Python, Node, and Go resolvers.

Per-SDK notes

• Python (AAASM-2028) — control_plane_url is a keyword argument on init_assembly, threaded into GatewayClient (httpx). The gRPC path (op_control) continues to read gateway_url.
• Node (AAASM-2029) — controlPlaneUrl is an optional field on AssemblyConfig. When set, the gateway client routes its HTTP traffic at it; the gRPC transport (op-control) keeps using gatewayUrl.
• Go (AAASM-2030) — assembly.WithControlPlaneURL stores the value on the runtime options for parity with the other SDKs. The Go SDK has no HTTP control-plane caller today (lifecycle is delegated to the aasm runtime), so the field is in place ready for the first HTTP caller; gRPC dial behaviour is unchanged.

Authoritative strategy source

The enterprise-vs-OSS connectivity strategy — why the second field exists, the transport split, and the per-SDK survey — is owned by agent-assembly-enterprise/docs/sdk-compatibility.md (filed under AAASM-1953). This section documents the OSS-visible surface of that convention; the enterprise doc is the authoritative source for the strategy.

CI Enforcement

A CI check (compat-matrix-check) enforces that this file is updated whenever version-carrying files change in a pull request.

Currently enforced (monorepo scope):

• Cargo.toml (workspace root)
• crates/*/Cargo.toml (all crate manifests)

Deferred — pending cross-repo CI integration:

• sdk/python/pyproject.toml (Python SDK)
• sdk/node/package.json (Node.js SDK)
• sdk/go/go.mod (Go SDK)

Until cross-repo CI exists, SDK version bumps require a manual update to this file before merging.

How to Update This File

When bumping a component version:

1. Add a new row to the Compatibility Matrix table for the new version combination.
2. Update the Minimum Supported Runtime Version table if the minimum changes.
3. Update the Supported Protocol Versions table if the runtime adds or drops protocol version support.
4. Commit the change in the same PR as the version bump.

See versioning.md for the full versioning and deprecation policy.

Workspace changes (non-version bumps)

Last updated: 2026-06-16 by Chisanan232

Protocol versioning policy

Use this page to decide how a protocol change must be versioned before you ship it. It defines the versioning scheme, the rules for classifying a change as breaking or non-breaking, and the deprecation lifecycle. Every change to proto schemas, JSON schemas, IPC framing, and wire formats is governed by this policy.

The short version: add fields and RPCs freely (MINOR); never remove, rename, or retype an existing field without a MAJOR bump and a migration guide.

Versioning scheme

The protocol uses Semantic Versioning (MAJOR.MINOR.PATCH):

The current protocol version is protocol/v1 (pre-stable: v0.0.1).

Change classification

Non-breaking changes (MINOR or PATCH)

These changes can be made without requiring SDK updates: