AI Agent Assembly Documentation

Quick links to each component, its current version, and its license. Every version badge reads the latest published version live — core and Go from GitHub, Python from PyPI, Node from npm’s rc dist-tag — so they stay current with no manual updates. The project is in release candidate (v0.0.1-rc).

AI Agent Assembly is a governance layer for AI agents. It sits between your agents and the outside world and does three things:

• Enforces policy — decides, before each governed action runs, whether an agent is allowed to call a tool, reach a domain, or spend more budget.
• Tracks cost — meters token and dollar spend per team and blocks agents that exceed their budget.
• Intercepts unsafe actions — the sidecar proxy denies a routed call before it leaves the machine, the SDK advises in-process, and the Linux eBPF sensor detects activity without returning a verdict. Each is deployed on its own and covers only what it is on the path of.

Governance applies per agent, on the paths you wire up — you do not have to rewrite your agent’s logic, but each agent has to be launched through a governed path (an SDK your code initializes, or the sidecar proxy). An agent started outside those paths is not governed. See Known limitations for what is measured, unmeasured, and unsupported today.

Who this documentation is for

This site is for teams, security engineers, and operators evaluating or running AI Agent Assembly for production adoption.

If you are a developer who wants to contribute or integrate at the code level, see the open-source documentation instead.

Find what you need

Pick the page that matches what you are trying to do.

SDKs & components

This hub is the central entry point for AI Agent Assembly documentation. To instrument your agents, you install the SDK for your language — each one ships its own documentation site. Use the table below to go to the SDK that matches your codebase (Python, Node/TypeScript, or Go), or to Arena, the cross-framework governance trial ground.

Every module’s docs are aggregated into this hub under a stable subpath (/core/, /python-sdk/, /node-sdk/, /go-sdk/, /arena/), so you can read and search all of them from one place. The standalone, per-version sites remain available for release-specific (mike / Docusaurus / Hugo channel) browsing.

Runnable examples

Prefer learning by running code? The examples repo collects small, framework-specific Agent Assembly examples for Python, Node.js/TypeScript, Go, policy enforcement, approvals, audit, trace, and runtime workflows. Clone it and run an example end to end to see governance in action before instrumenting your own agents.

The interception mechanisms

Governance is assembled from independently-deployable interception mechanisms, and a deployment runs whichever subset it installs. They are not a fallback chain and not a ranking: each reaches a different claim level, and a mechanism you do not deploy is reported as absent rather than picked up by another. The numbering below is presentational and implies no order of precedence:

1. SDK layer (in-process) — the language SDK wraps your agent’s framework tool calls and raises on a deny before the wrapped call runs. Fastest path, but advisory: it requires you to adopt the SDK and call its initializer, a non-cooperating process simply never calls it, and it does not intercept raw HTTP, subprocess spawns, or file access. Treat it as defense-in-depth, not the gate.
2. Sidecar proxy (aa-proxy) — intercepts outbound HTTP/1.1 that is routed to it, using per-host certificates minted from a local root CA, so it can govern agents that do not use the SDK. No agent code changes, but the process must honour HTTP_PROXY/HTTPS_PROXY and trust the CA (on macOS the install is attempted at proxy start via security add-trusted-cert, which requires admin authorization — macOS prompts, and a refusal fails proxy startup; on Linux run sudo aasm proxy install-ca; Windows is unsupported). On MitM’d hosts, HTTP/2, gRPC, and WebSocket cannot be inspected — on other hosts they are tunnelled uninspected.
3. eBPF sensor (aa-ebpf) — kernel hooks that watch OpenSSL and process syscalls. Observe-only: it reports what it sees and is consulted in no allow/deny decision, so its claim level is Observed and Detected — never prevention. It does not block, and it is not a mechanism the others fall back to. Linux only (the file-I/O kprobes are x86_64-only), and it degrades rather than failing closed if it cannot attach.

Each mechanism reports to the gateway, which evaluates policy and tracks per-team budgets. Coverage is the union of the layers you deploy, bounded by each layer’s own precondition — see Known limitations.

These interception points describe where a decision is applied; they sit inside the Boundary layer of the broader five-layer defense model, which describes what is protected. Same system, two views.

Last reviewed: 2026-06-27 — AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Documentation

AI Agent Assembly ships as five independently versioned programs, each with its own documentation site. This page is the central router — pick the program you are working with and follow the link to its docs.

Each documentation site has its own version selector — use it to view a specific release, a pre-release, or an older version.

Every link below points at the component’s site root, which always redirects to its newest stable release, so these references never need maintenance.

Core

• agent-assembly — the core monorepo: gateway, policy engine, eBPF sensor, sidecar proxy, FFI, WASM, CLI, and API.

SDKs

• Python SDK — install and govern agents from Python.
• Node SDK — install and govern agents from TypeScript or JavaScript.
• Go SDK — install and govern agents from Go.

Also on this hub

• Arena — watch AI agents from different frameworks attempt real and adversarial scenarios while agent-assembly enforces every decision, and read the published match reports.

Last updated: 2026-07-11 by AI Agent Assembly Team

What ships today

What governs this page

This page is an inventory, not a promise. It answers one question — what is available right now, and on what evidence — and it answers it from a machine-readable source rather than from prose.

Ticket references on this page are plain text, not links: the tracker is not publicly readable, so a link would only reach a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

Every table below is generated from governance/capability-manifest.yaml in the ai-agent-assembly/agent-assembly repository — the capability and evidence manifest defined by AAASM-5531 — through the pinned extract capability-surface.toml in this repository.

Manifest version 1.0.0 · 80 capability rows · taken at commit e2730ddaf · the manifest’s own evidence tree 299de3883, dated 2026-08-06 · declared fix version agent-assembly v0.0.1-rc.7.

The extract is refreshed by hand, so it can lag the manifest. What this repository’s CI proves is that the generated tables on these pages match the extract — prose outside the generated blocks is not checked, and proving the extract itself matches the manifest needs a cross-repository check, which is AAASM-5600.

Two different words are spelled Planned, and this page prints one of them. In the tables below it is ADR 0033 §6’s term, about an action: decided but not implemented, carrying a ticket reference and no capability claim. The 🗺️ Planned beside a page title in the sidebar is a documentation-area label from the status map, about how finished an area of this documentation is. Neither licenses a conclusion about the other: a 🧪 Release candidate area can be Unsupported on a platform, and a shipped feature can be Unmeasured on a path.

Level 1 — one sentence

Agent Assembly ships a governance decision point and an evidence trail for actions you have routed onto a governed path, on Linux and macOS, and this page lists what each area reaches and where it stops.

Level 3 — for an evaluator

What each claim term covers today

Every manifest row carries exactly one ADR 0033 §6 term. Two of §6’s eleven have no row at all, and that is shown rather than left out — their absence is a fact about the manifest, not a hole in this table.

Approval required having no row does not mean approvals are absent from the product; it means no capability row’s outcome is recorded as that term. Planned having no row is what §6 asks for: the term carries a ticket reference and no capability claim, so it belongs beside a ticket rather than in an inventory of what exists.

Where those outcomes sit

Host actions are shell and subprocess, files, browser automation and database queries. The other area names carry their scope on their face; the manifest’s own enum value is printed beside each so a rename cannot hide in a display label.

Read the counts as counts of manifest rows, not of features and not of code paths. A row is one question the manifest asked and answered; an area with more rows was examined in more places, not necessarily covered in more places. The per-mechanism version of this question — which term each named mechanism reaches — is Product promise’s, and is not repeated here.

Platforms

Host-level interception is per platform, and a platform without an adapter has none. There is no lower mechanism that picks up what an absent one would have done, and eBPF is one Linux mechanism rather than a cross-platform floor.

The authoritative platform matrix — including what transport mediation reaches on each platform, and the macOS row, which ends with an instruction not to read it as no host enforcement on macOS — is ADR 0033 §5.3. The table above is the manifest’s view of the same question and defers to it.

Where the artifacts come from

Distribution is per channel and per platform: a capability can ship on one channel and not another, and absent from a list is not the same statement as not shipped there. The manifest can record the second only for the container-image channel today. That mechanism was added by AAASM-5680 and has not been extended to the other seven.

Channels the manifest surveyed: github_release, homebrew, install_script, crates_io, pypi, npm, go_modules, ghcr, not_applicable. Channels it did not survey: none.

So on every channel except ghcr, a row that does not list a channel is telling you only that it does not list it. Do not read a not recorded cell as a zero. Which container images exist, and how their tags move, is Docker & containers’s.

What stands behind the rows

A capability row is worth what its evidence is worth. The manifest separates a test it can point at from a test it was told exists but could not locate, and separates both from a recorded gap — then separates all three from whether that evidence actually runs.

A recorded gap is not a silence. It is the manifest saying, in the row itself, that no test backs this and why. To take any single published sentence to the evidence behind it, start at Check a published claim.

What this page does not answer

• Whether a control is on. Shipping, buildable and activated are three separate questions. A capability can be in an artifact you installed and still be off, or reachable only when an environment variable names a process.
• Whether your agent is on a governed path. Coverage is a per-host, per-launch fact rather than a property of the architecture. Start at Choose your enforcement path.
• What a term means. ADR 0033 §6 defines the vocabulary; this page prints it.
• How finished an area of documentation is. That is the status map’s maturity label, on a different axis from anything here.
• Whether the extract is current with the manifest. This repository’s CI proves the pages match the extract. Nothing here proves the extract matches upstream; that check is AAASM-5600.

The managed service is not in these numbers

The Cloud control plane and the Enterprise operations features are documented as intent. Their documentation areas carry the status map’s 🗺️ Planned label, they have no rows in the capability manifest, and nothing on this page should be read as saying that either can be provisioned or operated today. What is written about them describes a design. Where the line between the open and the commercial side falls is the Open core boundary’s to state.

Deeper

The implementation-level answer — which crate does what, at which source line, and the highest term each mechanism can legitimately reach — is ADR 0033 in the Core documentation. The manifest this page is generated from is governance/capability-manifest.yaml.

Generated content on this page is rendered by docs/scripts/generate_capability_surface.py from capability-surface.toml. Do not hand-edit between the BEGIN/END GENERATED markers — AAASM-5609.

Last reviewed: 2026-08-13 — AI Agent Assembly Team

Last updated: 2026-08-20 by AI Agent Assembly Team

Choose your enforcement path

What governs this page

Three governed paths exist, they are independent of one another, and choosing between them is a decision about your platform and launch model rather than about the product’s architecture. This page sets out what each one needs, when it decides, what it does when it fails, and — at the same length — what it does not cover.

Ticket references on this page are plain text, not links: the tracker is not publicly readable, so a link would only reach a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

Every table below is generated from governance/capability-manifest.yaml in the ai-agent-assembly/agent-assembly repository — the capability and evidence manifest defined by AAASM-5531 — through the pinned extract capability-surface.toml in this repository.

Manifest version 1.0.0 · 80 capability rows · taken at commit e2730ddaf · the manifest’s own evidence tree 299de3883, dated 2026-08-06 · declared fix version agent-assembly v0.0.1-rc.7.

The extract is refreshed by hand, so it can lag the manifest. What this repository’s CI proves is that the generated tables on these pages match the extract — prose outside the generated blocks is not checked, and proving the extract itself matches the manifest needs a cross-repository check, which is AAASM-5600.

Level 1 — one sentence

Pick a path by what you can change — your agent’s code, its network route, or its host — then read what that path does not cover before you plan around it.

Level 3 — for an evaluator

The three paths, side by side

Grouping the manifest’s rows onto these three is this page’s doing; every fact rendered under a group is the manifest’s. The grouping follows the roles ADR 0033 §1 names and the components it lists against each. It is deliberately not a partition of the whole manifest — the rows no path claims are listed further down rather than forced into one.

The paths do not form a chain. A path you do not deploy is absent, and its absence is a reportable state rather than something the next one picks up. Deploying two does not compose them into a stronger single control; it gives you two controls with two separate boundaries.

What is not a path

Three things are routinely mistaken for a fourth path, and each mistake changes what you would plan for:

• The control plane is not an interception point. It holds policy, identity, budgets, approvals and audit, and it answers decision requests — but no agent bytes traverse it, so a refusal it issues stops something only when a component in front of the action blocks on the answer. Which components do, and which refuse on their own local configuration instead, is ADR 0033 §2’s caller table. Attribute a refusal to whichever component actually made it.
• eBPF is one Linux mechanism, not a cross-platform floor. It is an implementation of the host-adapter role on Linux only, and on the other platforms nothing takes its place. See what ships today.
• Writing a tool’s own settings file is not data-path mediation. It is tool-governance: it takes effect only if the tool honours those keys. Any data-path refusal such an integration delivers is the proxy’s, borrowed through the launch environment the integration injects. These rows are listed separately for that reason.

Path 1 — Managed execution checkpoints

What you change: your agent’s code, or the framework adapter it initialises. The checkpoint is a call your process makes before running a tool.

Who it suits: teams that own the agent’s source and can adopt an SDK.

What this path does not cover. Every row below is one the manifest records at Unmeasured or Unsupported — nothing is known about the action, or the mechanism is not available at all.

Two properties of this path decide whether it fits, and neither is visible from a quickstart:

• The checkpoint is voluntary. It is a call the agent makes. A process that does not make it is outside the boundary, and the product knows nothing about that action — not that it was allowed, and not that it was clean.
• Honouring a refusal is the shim’s job, not the client’s. ADR 0033 §4 records that the in-repo decision helper has no caller that refuses to execute, and that one out-of-repo shim maps transport failures to allow. Read the per-language rows above before assuming a returned refusal stops anything.

Path 2 — Protocol and transport mediation

What you change: the agent’s network route — an injected proxy environment and a trusted certificate authority — rather than its code.

Who it suits: teams that cannot modify the agent, including closed-source and vendor tools, on a platform where the mediator runs.

What this path does not cover. Every row below is one the manifest records at Unmeasured or Unsupported — nothing is known about the action, or the mechanism is not available at all.

Three defaults on this path are worth setting expectations against before you plan:

• Inspection is opt-in per host, not blanket. Only a built-in set of provider hosts is intercepted by default; everything else is tunnelled through without its payload being looked at. Widening that is an operator decision with a latency and compatibility cost.
• The egress lists are empty out of the box. An allow/deny decision at connection time decides nothing until you populate them.
• The mediator is not packaged everywhere. On macOS it arrives through crates.io only; see the channel table in what ships today.

Path 3 — Platform-specific host-level interception adapters

What you change: the host — a privileged component installed beside the agent.

Who it suits: Linux operators who need a view of process, file and TLS activity that does not depend on the agent cooperating.

What this path does not cover. Every row below is one the manifest records at Unmeasured or Unsupported — nothing is known about the action, or the mechanism is not available at all.

This path is the one most often planned against optimistically:

• It is predominantly an observation mechanism. Its probes feed the evidence pipeline and are consulted in no allow/deny decision.
• Its one terminating control is off unless you name a process, and it acts after the offending call rather than before it — which is why the manifest records it at Detected rather than at a pre-execution refusal.
• There is no adapter on macOS or Windows, and the rows above say so rather than leaving it to inference. Read the macOS position together with ADR 0033 §5.3, whose macOS row carries a qualification a summary reliably drops.

The launch route, which is not itself a path

A managed launch is how an agent or developer tool is placed onto one of the paths above — it injects the environment, and it writes settings into the tool’s own configuration. Its rows are here rather than under a path because a settings write is not a claim about the data path.

Supported tool and governable tool are different lists. One shipped adapter returns a launch failure rather than a governed command, and another is capped at observation; for those, no proxy environment is injected and there is nothing to route into.

Rows no path above claims

These are the manifest rows the three paths do not account for. They are published rather than dropped, because a row that quietly belongs to no path is exactly the kind of coverage assumption this page exists to prevent.

Most are cross-cutting — identity, credentials and the control plane’s own failure modes apply to whichever path you pick. The host-action rows are not: they are actions for which no mediation mechanism exists at all.

What none of these paths gives you

• A durable audit record from the SDK’s own interceptor. On the shipped path, a governed tool call through an SDK’s interceptor does not produce one — a caller-supplied handler does receive the record, but the SDK wires nothing itself. That capability is Planned in ADR 0033 §6’s sense: decided, not implemented, tracked as AAASM-5750, and carrying no capability claim until it lands. Audit evidence produced elsewhere in the system is a different question, and Check a published claim is how to take any single sentence about it to its evidence.
• A statement that an uninspected action was fine. Where nothing inspected an action, the honest report is that nothing is known about it. An absent audit entry is a fact about the observer, not about the agent.
• Coverage as a property of the architecture. It is a per-host, per-launch fact. Two hosts running the same version can have different answers.
• Anything from the managed service. The Cloud control plane and the Enterprise operations features are documented as intent, carry the status map’s 🗺️ Planned documentation-area label, and have no rows in the capability manifest. Nothing here should be read as saying either can be provisioned today.

Deeper

The role model these three paths are named after, the caller table behind the control plane’s position, and the verified platform matrix are all in ADR 0033 in the Core documentation. The manifest this page is generated from is governance/capability-manifest.yaml.

Generated content on this page is rendered by docs/scripts/generate_capability_surface.py from capability-surface.toml. Do not hand-edit between the BEGIN/END GENERATED markers — AAASM-5609.

Last reviewed: 2026-08-13 — AI Agent Assembly Team

Last updated: 2026-08-20 by AI Agent Assembly Team

Product promise & message hierarchy

This page is for anyone writing public copy about AI Agent Assembly — the product website, this hub, a README, a conference abstract, a sales deck. It exists because the product’s honest value is narrower than its architecture diagram suggests, and narrower still than the words the category usually reaches for. A reader who discovers an overstated claim after provisioning is a worse outcome than one who reads an accurate limit up front.

It is also for evaluators. Levels 1 to 3 below are the fastest accurate account of what the product does, what is on by default, and what it leaves uncovered.

What governs this page

This brief is downstream of two merged artifacts, and it does not add claims to them:

Ticket references on this page are plain text, not links: the tracker is not publicly readable, so a link would only take a reader to a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

Two further sources are chartered but not yet available, so nothing here depends on them: the current-state capability matrix (AAASM-5527, in progress) and the machine-readable capability/evidence manifest (AAASM-5531, not started). Statements that would need either of those to be verified are collected under Provisional rather than asserted.

Precedence. Where this hub still carries the superseded three-layer or “IronClaw five-layer” framing — Security model still carries the five-layer model, at the time of writing; AAASM-5727 removed the three-layer framing and the fallback-chain wording from it and from Glossary — ADR 0033 wins, and ADR 0033 records the gap as a tracked, accepted window. Do not resolve a conflict in the superseded model’s favour.

The two are not equally owned. security-model.md is named in ADR 0033’s migration checklist and is covered by AAASM-5586 / AAASM-5609. glossary.md was named by neither — not by the checklist and not by the claim inventory, whose docs rows reach only README.md and comparison.md — so its residuals sat unowned while looking tracked. Now AAASM-5658, which covered two defects: the eBPF entry saying the sensor catches what the layers above miss — corrected by AAASM-5727 — and the SDK entry, which still says the SDK applies allow/deny decisions, contradicting the advisory finding. That ticket also adds the file to ADR 0033 §E, so the next sweep cannot miss it for the same reason this one did.

Note also that this rule is one-directional — a reader who arrives at those pages first never sees it — so the migration tickets, not this note, are the fix.

Maturity labels (🧪 Release candidate, 🗺️ Planned) belong to Source of truth & status and answer a different question — how finished a feature is. ADR 0033 §6’s terms answer what the product did to an action, when, and on what evidence. The two are orthogonal: a 🧪 Release candidate feature can be Unsupported on a platform, and a shipped feature can be Unmeasured on a path. Cross-reference them; never let one redefine the other.

The promise

There is exactly one. Everything else on this page is a rendering of it at a different depth.

Agent Assembly decides whether an AI agent’s action is allowed before that action runs — on the paths you route through it — and records what was decided, so a risky call can be refused, or blocked pending a decision, instead of discovered afterwards.

Headline and subheadline

For a hero or a first screen, the promise renders as:

Headline

Decide what an AI agent may do — before it does it.

Subheadline

Agent Assembly evaluates the actions you route through it against your policy, refuses them, or blocks them pending a decision, and records what it decided. An action you have not routed through it is not inspected — and the record says so.

These two are not severable. The headline is bounded only by the subheadline; published alone it reads as a claim over all agent behaviour. That is the absolute claim class, which accounts for 37 of the 69 audited rows in the AAASM-5528 inventory — by some distance the most common defect in this product’s published copy. The rule for downstream pages is: the boundary clause appears on the same screen as the headline, above the fold, not in a footnote.

Note what the headline deliberately does not say: “your AI agents”. The possessive quantifies over agents you never routed, which is the wording the table below bans, and it is the same correction AAASM-5528 applied to “three boundaries for every agent” → “for a governed agent”. The indefinite article costs nothing and survives the places non-severability cannot reach — a <title>, an og:title, a search snippet, a chat unfurl, a slide. Metadata surfaces must carry the bounded form, because there is no room beside them for a subheadline.

Clause map

Each clause is expressible in ADR 0033 §6’s vocabulary. If a rewrite of the promise cannot be mapped this way, it is not a rendering of the promise — it is a new claim, and it needs its own evidence.

Progressive disclosure — four levels

A reader should be able to stop at any level and hold a correct picture. Each level adds precision; none of them retracts what the level above said.

Level 1 — one sentence

The promise, verbatim. Nothing shorter is approved, because everything shorter drops the boundary clause.

Level 2 — three steps

1. Route it. An agent is on a governed path when you have put it there: launched through aasm run, or started by a developer-tool integration that writes the proxy settings into the tool’s own configuration, or calling a policy checkpoint from an SDK. Routing is a thing you do, per agent and per launch. An agent you did not route is not on the path.

Not every tool has a managed launch to offer. One shipped adapter returns a launch failure rather than a governed command, and another is hard-capped at observation — for those, no proxy environment is injected and there is no data-path mediation to route into. “Supported tool” and “governable tool” are different lists; check the per-adapter boundaries before implying the second.

2. Decide it. Before the action takes effect, something on the path decides whether it may proceed — and which thing depends on the path. The control plane answers policy, budget and approval questions: allow, refuse, or block pending an approval. Budget exhaustion, a suspended agent and an anomaly detection each resolve to a refusal through that same path.

But the control plane is not always the decider, and copy that says it is will be wrong more often than right. The proxy refuses on its own local configuration for CONNECT-time egress and for LLM-provider hosts — those code paths contain no gateway call at all. A gateway Deny stops bytes in exactly one place: an MCP tool-call envelope on a non-LLM intercepted host with a gateway endpoint configured — and since llm_only defaults to on, those hosts are not intercepted unless an operator says so. Attribute the refusal to whichever component actually made it.

Redaction is a separate stage, not a fourth branch of the same answer: it is the proxy’s outbound credential scan, applied after the connection decision, and it defaults to redact-and-forward. Do not present allow/refuse/hold/redact as one four-way per-action verdict — the API’s five-way RuntimeVerdict is a frozen vocabulary whose derivation is unimplemented and which is surfaced as null, and presenting it as a live outcome is a forbidden design.

3. Show it. Decisions are written to a hash-chained audit log that you can verify yourself with aasm audit verify-chain — that command ships in the open-source build. Where nothing inspected an action, the rule is that the record reports it as Unmeasured rather than as clean, because an uninspected action must never be reported as allowed.

State this as a rule, not as finished behaviour. ADR 0033 §4 mandates it, and the transparent-tunnel path implements it — it persists “forwarded, and nothing looked at it”. But §2 records a live defect on the same path: the CONNECT-level decision event still emits an allow for a connection the proxy is about to tunnel uninspected. Until that is fixed, do not write copy that promises the property holds everywhere today.

Emission is best-effort — say so in the same sentence. The gateway advances the chain head before attempting the send, and on a full channel it logs a warning, increments a drop counter and returns the RPC anyway; several sibling emit sites discard the error with no counter at all. So a decision can be made and its record lost, and a dropped entry is indistinguishable from a deleted one. Three bounds belong together wherever this is claimed: which actions are decided (the governed path), whether the record survives (best-effort), and what verification proves (chain integrity, not whether the log is whole). The boundary clause in the promise covers only the first. This is the same rule-plus-open-defect shape as the note above, and the hub’s own security model already states that absence of an entry is not proof of absence.

Why “route it” is step one. The control plane holds no traffic, so a decision only stops something when a component in front of the action blocks on it. That set — components that block on a gateway answer — has exactly two members today: the proxy’s MCP path, and an SDK shim that honours the answer. It is not the set of everything that can refuse: the proxy’s own CONNECT, DLP and LLM-host refusals are local, and they are real. Routing is what puts an action in front of any of them.

Level 3 — for an evaluator

Agent Assembly is a decision point you place in front of an AI agent’s actions, plus the evidence trail that shows what it decided.

What it decides. Which tools an agent may call, which network destinations it may reach, how much it may spend, and which actions are blocked pending an approval. Policy is versioned YAML/JSON you review through normal Git workflows.

Where the decision is applied. In several places, with genuinely different authority. Resist the urge to number them: they are not an ordered chain, one does not cover for another, and an absent one is a reportable state rather than a silent hand-off to the next. That inference — “the SDK did not see it, so the kernel did” — is the specific error the current architecture exists to stop.

• The sidecar proxy is the strongest one. It refuses at CONNECT time, re-checks the host inside the tunnel, blocks or redacts recognised credentials, and adjudicates MCP tool calls — each of those returns before it dials upstream. This is genuine pre-execution refusal, out of the agent’s process.
• The SDK wraps your framework’s tool seam and raises before the wrapped tool body runs. It is deliberately advisory: it is a defence-in-depth posture, not the authoritative gate, and an agent that does not call it is simply not asking.
• Operating-system-level controls are platform-specific and, where they exist today, they mostly observe. On Linux, eBPF probes report TLS plaintext, process execution and file I/O; they do not participate in any allow/deny decision. There is one opt-in syscall guard that terminates a confined process, and it does so asynchronously — the offending syscall runs once before the process dies, so it is Detected, not Denied before execution. macOS has no equivalent adapter, and is simultaneously the only platform where the host-enforcement rung is reachable — through an opt-in, authorized managed-settings write. Both halves are required; writing only the first is the understatement this page bans two sections down. Windows has neither.

What is on by default, and what is not. This is the question that most changes an evaluation:

What it does not do. It does not govern an agent you did not route. It does not inspect payloads to hosts it is not intercepting. It does not keep a credential out of the agent’s own process — what it does is scan outbound requests on the inspected hosts and remove recognised credentials before forwarding. Its audit chain is tamper-evident, not signed: it is an unkeyed digest chain over the JSONL sink, so anyone able to rewrite that file can recompute it, the database mirror carries no chain, and a dropped entry fails verification the same way tampering does. Nor does a passing verification mean the log is whole — it checks the links between the entries that are there, so a deleted-and-recreated log verifies clean. On Windows there is no local mediation at all.

Level 4 — technical handoff

At this depth, stop paraphrasing and hand the reader the canonical sources. ADR 0033 describes the architecture as six roles — a control plane, managed execution checkpoints, protocol/transport mediation, platform-specific host-level adapters, a credential/capability boundary, and an evidence pipeline. A deployment instantiates some subset of them, an absent role is a reportable state rather than a silent fall-through to another role, and each role’s authority is its own.

Send the reader to ADR 0033 §5.3 for the per-platform matrix and §6 for the vocabulary itself. Do not restate either here; both are snapshots of a specific release and are maintained where they live. One thing §5.3 says that a summariser reliably drops: its macOS row ends “Do not read this as ‘no host enforcement on macOS’.” Carry that sentence with the row, not just the row.

Approved plain-language wording

ADR 0033 §6’s terms are precise but they are engineering vocabulary. Public copy needs plain-language equivalents that mean the same thing to a PM, an SRE and a security reviewer. These are the approved renderings. Use the plain form in body copy; keep the §6 term available wherever a reader might need to verify the claim.

Two subtleties worth carrying into copy, because both have already produced defects in this repository:

• Unmeasured is scoped to the action, not the connection. A host the proxy does not intercept is still adjudicated at CONNECT by local egress policy, and that connection is recorded. The honest phrasing is “the connection was observed, the payload was not inspected” — not “nothing was observed”.
• An empty audit log is evidence about the observer. It is not evidence that an agent did nothing. Never present a quiet log as a result.
• macOS needs its own sentence, in both directions. It has no kernel-level interception adapter, and saying so is required. But it is also the only platform on which the host-enforcement rung is reachable today, through an opt-in, authorized managed-settings write. Copy that flattens this into “no host enforcement on macOS” is an understatement defect, and it has been fixed once already — do not reintroduce it. State the route; leave the outcome under Provisional.

Rejected wording

Each row was removed from published copy, or considered and refused, for the reason given. The list is short on purpose: it names the patterns that keep recurring, not every sentence ever corrected. The audited per-file record is the AAASM-5528 inventory.

On the constellation identity

AAASM-4084 introduces Argo Navis as a product alias and visual identity. It is a naming and design layer, and it composes with this brief in one direction only: the metaphor may decorate the promise, it may not stand in for it. A page whose first screen explains a constellation before it explains what happens to an agent’s action has not made the promise; it has deferred it. Where the two compete for the same space, the promise wins.

Altitude — how this relates to the company-level description

Horonomy describes Agent Assembly at company altitude as a governance layer for AI agents — permissions, approval checkpoints, and evidence, which decides which tools, domains, and budgets an agent may use, holds risky actions for human review, and records what happened.

That is correct and this brief does not contradict it. The promise on this page sits one layer below: it keeps the same three ideas — permissions, approval, evidence — and adds the two things a product page must carry that a company page need not, namely when the decision happens (before the action) and where it applies (the paths you route through it). Do not “simplify” a product page back up to company altitude; the boundary clause is what makes it a product claim rather than a category description.

Claim-to-evidence mapping

Every material statement above traces to a merged, re-verified source. E1–E7 are the evidence blocks in the AAASM-5528 inventory; §n refers to ADR 0033.

Provisional

Not asserted in public copy until the owning work lands. Each is here because it is plausible and unverified, which is exactly the category that produces an overstatement.

Using this on a page

For the homepage rewrite (AAASM-5585) and the Product / How It Works rewrite (AAASM-5586), and for any page that makes a product claim:

1. Quote the promise, do not paraphrase it. A paraphrase is a new claim. If the layout needs a shorter line, use the headline — and put the subheadline with it.
2. Keep the boundary clause above the fold. Not a footnote, not a tooltip, not a “learn more”.
3. Pick a §6 term for every verb. If the sentence works with “protects”, “enforces” or “catches”, it is not yet specific enough to publish.
4. Name the mechanism that delivers the guarantee. The right guarantee attributed to the wrong component is its own defect class, and it is the one a technical evaluator notices first.
5. State the default. A capability that exists but is off is a different product from one that is on. The Level 3 table is the reference.
6. Check the direction of the error both ways. Understatement is also a defect — approval holds, pre-dial refusal, the SSRF guard and chain verification all ship, and a page that hedges them away is as wrong as one that overstates.

Last reviewed: 2026-08-06 — AI Agent Assembly Team

Last updated: 2026-08-13 by AI Agent Assembly Team

Risk scenarios — the flagship story and three supporting threats

This page selects the four stories the product’s public surfaces tell: one flagship scenario for the homepage, and three supporting scenarios covering secret exfiltration, a destructive production action, and runaway cost. It exists so that the website, this hub and the demo assets tell the same four stories in the same words, and so that each of those words can be traced to something the product actually does.

It is narrative source material, not a product page. Downstream surfaces (AAASM-5585, AAASM-5589) copy the wording in Approved wording for reuse verbatim rather than paraphrasing it — a paraphrase is a new claim and carries its own evidence burden. That section is split into two tiers: Tier 1 is publishable today; Tier 2 is held until the prevented-outcome harness lands (AAASM-5532, AAASM-5529). Check the tier before shipping a sentence.

What governs this page

This page adds no claims to its sources. Where it appears to, that is a defect in this page.

Ticket references are plain text, not links: the tracker is not publicly readable, so a link would only reach a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

Vocabulary precedence is not decided here. These scenarios are written in ADR 0033 §6’s terms because the promise page already is. Where §6’s vocabulary collides with another controlled vocabulary on this hub, that conflict belongs to AAASM-5621, which owns precedence across the hub’s content layers — record it there rather than resolving it on this page. This page follows the same deferral AAASM-5595 makes.

The promise these scenarios render. Agent Assembly decides whether an AI agent’s action is allowed before that action runs — on the paths you route through it — and records what was decided, so a risky call can be refused, or blocked pending a decision, instead of discovered afterwards.

The clause “on the paths you route through it” is load-bearing in every scenario below. None of these stories is a claim about an agent you did not route, a host you are not intercepting, or a platform without the component installed.

How to read a scenario

Each scenario carries eight fields, plus a determination.

Determination is one of:

• Executable today — the mechanism exists, a released binary can reach it, and a standing test on the core repo’s default branch exercises it. The scenario’s defaults and platform boundaries are still stated.
• Executable, default-off — as above, but nothing happens until an operator turns it on. A sentence that is true “once enabled” is false as written.
• Illustrative / planned — the story is useful for explaining the product’s shape but does not correspond to a capability a reader can exercise. It must be labelled wherever it is used.

Every capability cited below was checked against four questions, each of which is invisible to the one before it: is it worded without absolutes; does the guarantee hold in code; is it on by default; and does the named mechanism exist at all and can a released binary reach it. Distribution is per channel and per platform — the core repo publishes through five channels, and absence from the release workflow proves nothing about crates.io.

Scenario status at a glance

Scenarios are lettered F and T1-T3 deliberately. AAASM-5527’s own row IDs use S for the SDK rows, and this page tells readers to cross-reference those IDs — an S1 here and an S1 there would collide on exactly the identifier a checking reader follows, on a page whose whole claim is that none of its scenarios is an SDK scenario.

Flagship — the upload that never happened

A coding agent tries to send the repository it is working on to an endpoint nobody approved. The connection is refused before it is dialled.

This is the flagship because the denied side effect is objectively testable in the negative: a socket either accepted a connection or it did not, and the check does not depend on trusting anything inside the agent’s process. Note the tense discipline — this section describes a decision and a testable design. The claim that the endpoint never received a byte is Tier 2, and waits on the harness actually being run.

Known boundary, in full — six parts, all load-bearing:

• The lists are empty by default. AA_PROXY_DENIED_HOSTS and AA_PROXY_NETWORK_ALLOWLIST are both empty out of the box (aa-proxy/src/config.rs:75-85), and the row’s default_state is open. This refusal exists because the operator configured it. Never tell this story as something that happens on first run.
• The always-on egress control is a different one. The SSRF guard (N2) is on by default, fails closed, cannot be relaxed by configuration, and re-checks every resolved address before dialling — but it blocks private and loopback address space, not an arbitrary public paste endpoint. It does not deliver this scenario; do not credit it with doing so.
• Bypasses are enumerated and published. Unsetting the proxy environment, a client that ignores it, raw TCP that does not speak the proxy protocol (N10), and UDP/QUIC/HTTP/3 (N11) all leave the boundary. The scenario’s scope is B3 — universal within one process, conditional on that process honouring the injected proxy environment. It is not host-wide.
• Channel and platform. aa-proxy ships in the GitHub Release, the Homebrew tap and the install script for linux_x86_64 and linux_aarch64 only — the release workflow states the proxy is a Linux-only component. On macOS the sole route is cargo install aa-proxy from crates.io (AAASM-5653). On Windows there is no local mediation at all (P4, Unsupported). A demo recorded on a macOS laptop is running a crates.io build, not a released artifact.
• Failure posture is fail-open on this path. If the proxy is not in front of the connection, the connection is simply made.
• The proxy writes no local evidence unless you configure a path. The proxy’s JSONL sink is built from AA_PROXY_AUDIT_JSONL_PATH (aa-proxy/src/config.rs:482-483, wired at aa-proxy/src/lib.rs:81); with the variable unset there is no writer and nothing lands on disk, which the crate’s own test pins as the default. The refusal still happens — this is a bound on the evidence, not on the decision — but a demo that promises a record must set the variable, and a page that promises one must say it is configured. Note also that this sink is the proxy’s own; the separate best-effort emission defect tracked as AAASM-5626 is on the gateway’s audit path, and attributing it here would be the wrong component.

Determination: executable, default-off. Rows N1 (reachability: shipped_with_platform_exception, standing evidence), N2, L1 (reachability: shipped, current_level: host_enforced, standing evidence).

Negative control for the flagship (AC 1)

A negative control proves the absence of the effect, not that an error was raised. An agent can receive a 403 and still have reached the endpoint by another route; an agent can raise an exception without ever having tried. Neither an error nor a stack trace is evidence that nothing arrived.

The observable side effect is a TCP connection carrying payload bytes arriving at the destination.

Instrumentation. Stand up a real listener on the address the egress configuration denies. It records, independently of the agent and of the proxy: the count of accepted connections, and the total bytes received. It is the only witness that matters, because it sits on the far side of the boundary — a probe on the near side can observe that its request went out and that nothing obviously failed, and neither fact is evidence.

A precondition the harness must set, and cannot set by environment. A loopback listener is inside the SSRF guard’s blocked set, so the guard — not the egress list — would refuse the connection, and the test would pass for the wrong reason while proving nothing about egress policy. The harness must construct its config with allow_private_connect_targets = true (aa-proxy/src/config.rs:161, default false at :184). No environment variable does this; from_env hardcodes it false, which is deliberate — production binaries cannot relax the guard. That makes the loopback-witness form an in-process test, not something a shipped binary can be driven into.

The test and the demo are different artifacts. The in-process test above uses a loopback witness and can therefore assert byte-level absence. A public demo driving a released aa-proxy cannot use a loopback witness at all — it needs a real remote endpoint under the demo’s control, and its absence evidence is that endpoint’s own access log rather than an in-process counter. Do not present one as the other, and do not claim the demo inherits the test’s rigour.

Three runs are required. All three, or the result proves nothing.

1. Positive control — the check can see the effect. With the destination host allow-listed, run the same agent action. Assert listener.accepted_connections == 1 and that the payload bytes arrived. This is what makes a later zero meaningful. Without it, “zero connections” is indistinguishable from a listener that was never listening, a harness that never started the agent, or a test that silently skipped.

2. Negative run — the effect is absent. With the destination denied, run the same agent action, then assert in this order:

   1. First: listener.accepted_connections == 0 and listener.bytes_received == 0. This is the load-bearing assertion and it must execute before anything that can throw, return early, or short-circuit.
   2. Then: the caller observed a refusal (403).
   3. Then: a decision record exists attributing the refusal to the proxy’s CONNECT-time egress check. The harness must set AA_PROXY_AUDIT_JSONL_PATH for this to be checkable at all — unset, the proxy writes no local evidence, and the assertion would fail for a reason that has nothing to do with enforcement.

3. Attempt witness — the agent actually tried. In the negative run, assert that the proxy recorded a CONNECT attempt for that host. Without this, zero connections at the listener is also consistent with an agent that never attempted the upload, which would make the test pass for the wrong reason.

   Two honest caveats. It overlaps step 2(c) — a decision record for the refusal already implies an attempt reached the proxy — so treat it as a cheap independent restatement, not a separate discovery. And it witnesses only that a CONNECT was attempted: it can never establish that the agent would have transmitted the payload, because the refusal precedes any body. The positive control is what establishes that the payload would have flowed.

Ordering is the whole point, and it has already gone wrong here — twice. Assert the absence before the error, never after.

State the defect precisely, because the loose version of it is wrong and gets dismissed. In the passing run both assertions execute, so nothing looks broken. The defect appears under falsification: if enforcement is removed or mutated, a test that asserts the error first aborts on that assertion, and the absence check — the one the control exists for — is never reached. The control therefore passes whether or not it can detect the thing it was written to detect, and it fails for the weak reason (“no error was raised”) rather than the load-bearing one (“the effect happened”). It has never been shown to bite.

This is the exact defect corrected across the three SDK negative-control suites under AAASM-5529 — in each repository one control had the wrong order while its siblings were already correct. Those corrections sit on unmerged branches at the time of writing, and AAASM-5529 is still open, so treat this as a known pattern to design against rather than as a solved problem. The same shape is present today in this scenario’s own area: in aa-integration-tests/tests/e2e_policy_proxy.rs, proxy_intercepts_and_enforces_deny binds a real upstream listener and asserts it is never accepted (:157-162), which is a genuine negative control — but its 403 assertion at :152 precedes that check. The other three deny tests in that file have no negative control at all: they target a hostname with no listener behind it, so there is nothing that could have observed an arrival. Whoever implements the flagship harness should treat proxy_intercepts_and_enforces_deny as the starting point and fix the order, not write a fourth test alongside it.

If the harness uses a construct that asserts a raise around a block, the absence check must sit outside and after that block, not inside it.

What this negative control does not prove. That the upload was impossible — only that it did not happen on this path, in this configuration, on this platform. The bypass list above is the honest scope, and it belongs next to the demo.

T1 — Secret exfiltration

An agent puts a live credential into a request to a model provider. The credential is recognised and removed before the request is forwarded.

Note the verb: Redacted, not Denied. The request proceeds. Copy that turns this scenario into a blocked request is wrong, and the difference is the default.

Known boundary, in full:

• Redact-and-forward is the default; blocking is opt-in. The default action is RedactOnly (aa-proxy/src/config.rs:16-27). A third mode, AlertOnly, forwards the credential unmodified and raises no alert — if a page says “alerts you”, it must not mean this mode.
• Three hosts, by default. llm_only defaults on, which intercepts api.openai.com, api.anthropic.com and api.cohere.com (aa-proxy/src/intercept/detect.rs:31-34). Any other host is tunnelled without payload inspection: the connection is Observed, the payload is Unmeasured. The honest phrasing is “the connection was observed, the payload was not inspected” — never “nothing was observed”.
• Recall is bounded by the pattern set, and the bound is wider on the release than on main. There is no Stripe detector, and the OpenAI detector keys on sk- while Stripe uses sk_. Splitting a secret across a multi-character gap still evades detection (aa-security/src/scanner.rs:3960-4005) — that is true in both places. The single-separator case differs: AAASM-5368 closed it on main (scanner.rs:1346, implemented at :1395, regression test at :3858), but it is still live in the published rc.6, where AAASM-5368 has zero occurrences. A reader running a released build therefore has a wider hole than a reader of the source. State the pattern-set bound wherever recall is implied, and say which build you mean.
• Model responses are not scanned. A credential coming back from the provider is Unmeasured.
• The stronger variant is real, off by default, and unit-evidenced only. Credential substitution — where the operator’s real provider key is appended at egress and the agent’s own header stripped, so the real key never enters the agent (aa-proxy/src/credentials.rs:198, aa-proxy/src/proxy/http.rs:353,371-383) — is a genuine shipped mechanism. But its default_state is false (the operator must set AA_PROXY_PROVIDER_KEYS), it covers only the intercepted hosts, and its evidence is unit-only: no end-to-end test proves the substitution reaches upstream. A bounded version of the “never enters the agent” claim is defensible with all of those conditions named, and not otherwise.
• Do not tell the credential-injection story. A separate mechanism — credential injection via SecretsService.DispatchTool — is dead code (reachability: dead_code, row C3). Copy claiming “secrets are injected at runtime and never enter the model context” advertises a capability no released build can reach, and it is already on the rejected-wording list. Conflating C3 with the substitution mechanism above is exactly what produced that defect.
• Channel and platform are the proxy’s, identical to the flagship’s.

Determination: executable today for the redaction path — rows C1 (shipped_with_platform_exception, standing evidence), C6 (detected, standing evidence), N3 (standing evidence). The substitution variant (C2) is executable, default-off, unit-evidenced. The injection variant (C3) is not executable — dead code and must not be told at all.

T2 — Destructive production action

An agent calls a tool that would drop or rewrite production data. The call is evaluated against policy and refused before the proxy forwards it.

As with the flagship, this section describes a decision. “The tool server never received the call” is the prevented-outcome form, and it is Tier 2 — held until the harness has run.

This is the one scenario in the set where the control plane makes the decision that stops the bytes. Everywhere else in this page, the refusal is the proxy’s own local configuration.

Known boundary, in full:

• One transport is covered, and it is not the one people assume. M1’s transport is plain HTTP/1.1 POST with an explicit Content-Length. Every other MCP transport is outside it, and M1’s own known_bypasses says so by listing “M2 through M9”:

  • stdio (subprocess pipes) — absent_mechanism (M5). This is the most common MCP transport in practice, and it is entirely unmediated. The product models stdio servers (aa-core/src/dev_tool.rs:112-121) and cannot mediate them.
  • SSE (text/event-stream) — absent_mechanism (M6); the SSE leg is raw-copied unscanned.
  • Streamable HTTP — coverage: unmeasured, and worse than uncovered (M7). Its failure_posture is silent_truncation: the client receives an empty 200. aa-proxy/src/proxy/http.rs:13 claims the MCP path falls back to a transparent relay; it does not. Never advertise this transport as governed — an earlier draft of this page did exactly that, which is the inversion this bullet exists to prevent.
  • WebSocket — Unsupported (M8).
  • An MCP endpoint on a built-in LLM host is DLP-scanned but never adjudicated (M9, coverage: redacted).

• Off by default, and the shipped CLI routes couple it to whole-machine interception — but the mechanism does not. The row’s default_state is false. Both CLI routes widen TLS interception to every host on the machine, which is a material operational consequence and not a footnote. The capability itself is narrower than that, and understating it is its own defect: should_mitm (aa-proxy/src/proxy/mod.rs:1385-1388) unions mitm_hosts, so AA_PROXY_GATEWAY_ENDPOINT together with AA_PROXY_MITM_HOSTS, leaving llm_only on, adjudicates exactly the hosts you name. What is missing is a CLI flag that produces that configuration — ergonomics and documentation, not capability. Do not tell an evaluator they must intercept the whole machine to get MCP adjudication.

  A source conflict, recorded rather than silently resolved. AAASM-5527’s two halves disagree here. The YAML’s M1 notes still says “the only supported route … forces AA_PROXY_LLM_ONLY=false”; the threat-model MD carries a bolded “Correction to an earlier revision, which called this ‘the only supported route’. It is not.” and finding F7 spells out the targeted alternative. This page follows the MD. The divergence is worth closing at the source.

• Only tools/call. Every other MCP method is Unmeasured (row M4).

• A hold cannot be reached here. A gateway Pending decision is downgraded to Deny inside the tunnel (mcp_enforce.rs:135-144), so this path cannot produce “blocked pending a human decision”. Separately, and more broadly, no shipped operator surface can answer a hold at all — see the Provisional row in Product promise (AAASM-5657). Do not attach an approval narrative to this scenario.

• Per-agent MCP policy and per-agent MCP audit do not exist and must not be claimed (AAASM-5533). The decision is not attributed to an individual agent on this path.

• The batch/malformed-envelope defence (M3) is unit-evidenced and has an open bypass. Its evidence_quality is unit_only — the wire-level test e2e_mcp_interceptor.rs has no batch case — and mentions_tools_call inspects only one level (aa-proxy/src/intercept/mcp.rs:128-130), so a nested batch, or one whose elements carry params without a literal top-level method, is not detected. For a fix to a bypass ticket (AAASM-4070) that coverage is thin; a wire-level negative control is owned by AAASM-5532. Cite M3 as a defence that exists, not as one that is wire-proven.

• Channel and platform are the proxy’s, identical to the flagship’s.

Determination: executable, default-off, over HTTP/1.1 POST with an explicit Content-Length on Linux — rows M1 and M3 (shipped_with_platform_exception, standing evidence). Not executable over stdio or SSE (M5, M6: absent_mechanism), and not over Streamable HTTP (M7: unmeasured, and functionally broken). A demo or a page that shows a local stdio MCP server being governed this way would be showing something that does not happen.

T3 — Runaway cost

An agent enters a retry loop, or fans out across a large repository, and keeps spending. The call that would cross the declared cap is refused by the policy decision.

Two disciplines apply here at once. “Refused rather than billed” is the prevented-outcome form and is Tier 2. And even the decision only stops the call where something in front of it blocks on the answer — which, for a model call, is not the default. See the boundary.

Known boundary, in full:

• No cap unless you declare one. Limit resolution returns nothing when neither a per-agent nor a global limit is configured, so an undeclared budget is uncapped spend. Most shipped policy examples declare a daily cap, so an evaluator who starts from one usually gets a cap — but a hand-written policy that omits the block has none.

• A corrupt or unreadable budget store fails open, silently, and resets the cap to zero spend. The gateway falls back on a load failure (aa-gateway/src/server.rs:260-268), and a write failure prints to stderr and continues (aa-gateway/src/budget/persistence.rs:85-86). Row G9’s failure_posture is fail_open_silent. This is the sharpest boundary in this page: the control is real, and the mode in which it stops working produces no signal on the decision path — it does emit a tracing::warn! (“failed to load budget state, starting fresh”), so an operator watching logs can see it; nothing downstream of the decision can. Any page that claims a spend guarantee must carry it.

• A refusal only stops something through a caller that blocks on the answer, and for a model call there is no such caller by default. The gateway holds no traffic. Budget exhaustion resolves to a refusal in the decision; whether that refusal prevents the call depends on the same two blocking callers as every other gateway decision — and neither covers this scenario out of the box:

  • The MCP path adjudicates tools/call on a non-LLM intercepted host. An MCP endpoint on a built-in LLM host is DLP-scanned but never adjudicated (M9), so an ordinary model call is not on it.
  • The SDK is advisory, and the Node default routes every check through an allow-all no-op (S7, AAASM-4991); the documented Python quick-start installs no interceptor at all (AAASM-5661).

  So by default this scenario yields Evaluated — a refusal decided and recorded — not a call prevented. Say “the cap was reached and the call was refused” only where one of those callers is genuinely in the path, and say which.

• The obvious test does not prove this scenario. aa-integration-tests/tests/e2e_budget.rs looks like the evidence and is not: all of its tests drive record_raw_spend directly and assert on the returned BudgetStatus, never calling check_action or the policy engine — its own header records the substitution at :15. record_raw_spend accounts for spend; it is not an authorization gate. Citing it for pre-execution denial would be a wrong-reason pass, which is why the Evidence field above names the gateway tests instead.

• A matrix gap, stated rather than hidden. AAASM-5527 assigns no positive capability row to budget enforcement — the only budget row in the matrix is G9, the failure mode, whose own evidence field is marked GAP. So this scenario’s determination does not rest on a matrix row the way the other three do; it rests on the call path and the gateway tests cited above. That is different provenance, and a reader is entitled to know which of these four scenarios has it.

Determination: executable today, with the silent fail-open stated alongside it. The call path is check_action (aa-gateway/src/service/policy_service.rs:1599) → evaluate → Stage 7’s budget check (aa-gateway/src/engine/mod.rs:1687-1691) → EvaluationResult::deny_with, with a TOCTOU-safe reservation for LLM spend rewriting the response to a hard Deny (policy_service.rs:1341, called at :1669). Derived from that path and its gateway tests, not from a 5527 capability row, because none exists.

T3b — Unauthorized payment: illustrative only

The parent scope pairs runaway cost with “unauthorized payment”. These do not have the same answer, and they must not be told as one story.

There is no payment, purchase, checkout or spend-authorization capability in the product. The argument is structural, not a grep: the policy engine’s action type GovernanceAction (aa-core/src/policy.rs:194) has exactly six variants — ToolCall, ToolResult, FileAccess, NetworkRequest, ProcessExec, SendMessage. None is a payment, and nothing can be evaluated that is not one of them. That cannot be falsified by a better search.

Expect to find payment vocabulary anyway, and do not mistake it for capability. process_refund appears roughly 45 times across 25-plus files — as a tool name in dashboard E2E fixtures and as an approval action in aa-cli approval-client tests — and a policy-YAML documentation example even grants it with limit_per_hour and requires_approval_if: "amount > 100". There are checkout-agent and refund-agent identifiers in aa-api route tests, and a v1 wireframe sketches an approval queue containing “refund $500 via stripe”. All of it is fixture, test or design material: demo data shaped like a capability, not a capability. An earlier draft of this page claimed a sweep “returns only three unrelated classes”, which was simply incomplete — the determination survived, the methodology boast did not.

A methodology note, because it invalidates negatives elsewhere too. git grep -E does not support \b. A sweep written as \bcharge|\bspend matches nothing and looks exactly like a real absence. Any negative finding derived from a \b pattern needs re-deriving with a positive control in the same command.

The nearest real controls are generic, and none of them knows what a payment is:

• refusing the connection to a payment API host — the flagship’s mechanism, and it treats that host like any other unapproved host;
• refusing an MCP tools/call that happens to be a payment tool — T2’s mechanism, with T2’s transport bound;
• the spend cap above, which counts model tokens, not money moved.

Determination: illustrative. If a surface needs a payment story to make the category legible, it must be labelled illustrative in place, and it must not be demonstrated as a product capability. In particular it must not be told as “held for human review” — that is a Provisional claim on the promise page, blocked on AAASM-5657, because no shipped operator surface can answer a hold.

Approved wording for reuse

These are the sentences downstream surfaces may use verbatim. They come in two tiers, and the split is not stylistic — it is a publication gate.

Why there is a gate. product-promise.md’s Provisional list defers “a named prevented-outcome demonstration” — any “we stopped X” — until the proof harness lands under AAASM-5532 and AAASM-5529. Both are open; this page says so itself. So a sentence asserting that an endpoint never received a byte, or that a call was refused rather than billed, is a claim this product cannot yet substantiate, however well-designed the negative control on this page is. Designing the control is not the same as having run it.

Tier 1 is publishable today. Tier 2 becomes publishable when those two tickets close and the harness has actually run — not before.

The gate binds the demo lane too. AAASM-5589 embeds a denied-action proof into the website, which is the prevented-outcome demonstration in its purest form — so it is more exposed to this gate than the homepage is, not less. A demo that shows an averted consequence is making the Tier 2 claim in the strongest available medium.

Three constraints on Tier 1, all inherited from product-promise.md:

1. Tier 1 sentences are not severable from the flagship boundary clause. The clause appears on the same screen, above the fold — not a footnote, not a tooltip, not a “learn more”. A Tier 1 sentence published alone reads as a claim over all agent behaviour, which is the single most common defect in this product’s published copy.
2. No scenario sentence on this page is approved for a metadata surface. A <title>, an og:title, a search snippet, a chat unfurl or a slide has no room for a boundary clause beside it — and constraint 3 forbids shortening one to fit. Use product-promise.md’s headline, which is written to survive exactly those places: “Decide what an AI agent may do — before it does it.” Its indefinite article is deliberate — “your AI agents” would quantify over agents nobody routed.
3. Quote, do not paraphrase. A paraphrase is a new claim and carries its own evidence burden. If a layout needs something shorter than what is here, that is a layout problem, not a wording problem.

Tier 1 — publishable now (decision-scoped)

Each of these describes what was decided, which is what the product can evidence today. None asserts an averted consequence.

Flagship, long form (for a homepage section):

A coding agent decided to upload the repository it was working on to an endpoint nobody had approved. Because the agent was launched through Agent Assembly’s managed launch for Claude Code, the connection was evaluated against the destination list the team configured, and refused before the proxy dialled it.

Flagship, short form (for a hero panel or a card):

The connection was refused before it was dialled.

Flagship, boundary clause — required on the same screen, above the fold:

This applies to connections you route through Agent Assembly — today, via the managed launch for Claude Code — on a host where the proxy is installed: a released artifact on Linux, and on macOS via cargo install aa-proxy. On Windows there is no local mediation. It applies against an approved-destination list you configure. An agent you did not route is not inspected, and the record says so. A durable local record of the refusal exists only where the proxy’s audit path is configured.

T1 — secret exfiltration:

An agent pasted a live API key into a request to its model provider. On the provider hosts Agent Assembly inspects, the key was recognised and removed before the request was forwarded. Detection is bounded by the patterns it knows, and the default is to redact and forward, not to block.

T2 — destructive production action:

An agent called a tool that would have dropped a production table. The call was evaluated against your policy and refused before the proxy forwarded it. This covers MCP tool calls sent as ordinary HTTP POSTs; tool servers you run over stdio (the most common setup), SSE, or Streamable HTTP are not on this path.

T3 — runaway cost:

An agent in a retry loop reached the spend cap its team had declared, and the next call was refused by the policy decision. A cap exists only where a policy declares one, and the refusal stops the call only where something in front of it waits for that answer.

Tier 2 — gated until AAASM-5532 and AAASM-5529 close

Do not publish these yet. They are recorded here so that the wording is settled in advance and nobody re-derives it under deadline once the gate lifts. Each states a prevented outcome, which is precisely what the harness must first demonstrate.

(Flagship) The endpoint never received a byte.

(T2) The tool server never received the call.

(T3) The call was refused rather than billed.

When the gate lifts, these attach to the Tier 1 sentences; they do not replace the boundary clause.

The four verbs these scenarios are allowed to use, and nothing vaguer: refused before it ran (Denied before execution), removed before it was forwarded (Redacted), evaluated against your policy (Evaluated), recorded (Observed). If a sentence works with “protects”, “enforces” or “catches”, it is not specific enough to publish.

What these scenarios must not be used to say

• Not “Agent Assembly stops your agents from leaking data.” Each scenario is scoped to one process, one routed path, one configured rule and one platform.
• Not “nothing gets past it”, “catches everything”, or “an agent cannot walk around it”. The bypasses are enumerated in each scenario and are published.
• Not a count, a percentage or any coverage figure derived from these four stories. There is no machine-readable manifest to compute one from, and self-reported layer availability is not evidence of coverage.
• Not “held for human review” on any of them. A hold is real and fails closed, but no shipped operator surface can answer it (AAASM-5657).
• Not an audit claim stronger than tamper-evident. The chain is an unkeyed digest, emission is best-effort, and a passing verification does not mean the log is whole.
• Not a story told on a macOS or Windows screenshot without its platform sentence. The proxy that delivers three of these four scenarios is a Linux release artifact; on macOS it is a crates.io install, and on Windows there is no local mediation.
• Not the credential-injection framing for T1. That mechanism is dead code.
• Not T2 over a stdio MCP server (no interception mechanism), and not over Streamable HTTP, which the matrix records as functionally broken rather than merely uncovered.

How this page meets its acceptance criteria

Last reviewed: 2026-08-06 — AI Agent Assembly Team

Last updated: 2026-08-06 by AI Agent Assembly Team

Security model

AI Agent Assembly is a governance layer for AI agents — it enforces policy, tracks cost, and intercepts unsafe actions before they run. This page documents the security posture behind that enforcement, for enterprise security and compliance teams. It covers the layered defense model, a STRIDE threat analysis, the cryptography in use, and the audit and compliance posture.

IronClaw five-layer defense

AI Agent Assembly groups its security controls into five named layers. Each layer is independently deployable and adds defense-in-depth. They are not a fallback chain: a layer you do not deploy is absent, not covered by another, and each row below states its own bound.

How the five layers relate to the interception mechanisms. The five defense-in-depth layers above (Boundary, Identity, Policy, Vault, Telemetry) describe what is protected. The interception mechanisms named on the landing page and marketing site — the SDK layer, the sidecar proxy (aa-proxy), and the eBPF sensor (aa-ebpf) — describe where a decision is applied, and each sits inside the Boundary layer. They are two views of one system, not two competing models. They are not an ordered pipeline and not a ranking: each is deployed on its own and reaches its own claim level, and an absent one is reported as absent rather than covered by another. Where this page and ADR 0033’s six-element model differ, ADR 0033 wins.

STRIDE threat model

The table below maps each STRIDE category to the five primary components of AI Agent Assembly and the control that mitigates it.

Traceability: Each STRIDE row maps to a specific IronClaw layer control. For configuration paths and runbook references, consult the security runbook in the agent-assembly repository.

Cryptographic primitives

Keys listed above are generated using a CSPRNG. MD5, SHA-1 and DES are not used by any primitive in this table — a statement about first-party code in the agent-assembly workspace, not about the full transitive dependency tree, which this hub does not audit.

Authentication flow

⚠️ Gateway auth is off by default. A bare aa-gateway boots with AuthMode::Off on its REST/admin surface — the zero-config aasm status path (and any other REST/admin route) is served with no credential until an operator explicitly opts in with AA_GATEWAY_AUTH=on and a valid AA_JWT_SECRET. This is unrelated to the gRPC agent plane below. aa-api (the dashboard API) defaults auth on; the gateway is the off-by-default surface. See Open core boundary for how this pairs with the self-host posture.

How the agent plane is actually authenticated. The credential-token interceptor is fail-closed on five services — audit, approval, topology, secrets and invalidation. It is not applied to PolicyService or AgentLifecycleService; those two are mounted with an enrichment interceptor that never rejects. That does not make them open: their handlers validate directly. Register requires the agent_id’s did:key to encode the supplied public key (rejected as Unauthenticated otherwise), consumes a single-use identity-bound server nonce, and verifies an Ed25519 possession proof — so an agent can only register as an identity whose private key it holds. Heartbeat, Deregister and the control stream validate the token, and CheckAction rejects a missing or mismatched credential token for an agent that is registered, including cross-identity reuse.

The one real gap: an unregistered caller presenting an empty token can still obtain a policy evaluation. Tenancy is not taken from the request in that case — it is neutralised to anonymous — so the caller gets a decision without an authenticated identity or tenant. Treat reachability of the port as the control that matters, and see the STRIDE table above.

SDK to gateway (gRPC)

sequenceDiagram
  autonumber
  participant SDK as Language SDK
  participant GW as aa-gateway

  SDK->>GW: RequestChallenge(agent_id, public_key)
  GW-->>SDK: nonce (single-use, server-random)
  SDK->>GW: Register(agent_id, public_key, possession_proof = sign(nonce))
  GW->>GW: Verify Ed25519 signature over nonce (one-time possession proof)
  GW-->>SDK: credential_token (random UUID, no expiry)
  Note over SDK,GW: All subsequent calls carry credential_token in gRPC metadata (x-aa-credential-token or Authorization: Bearer)

  SDK->>GW: CheckPolicy(event) [+ credential_token]
  GW->>GW: Constant-time compare against stored token (no TTL — tokens do not expire)
  GW-->>SDK: PolicyDecision

Operator authentication

Operators authenticate to the REST/admin surface with an API key or a JWT — the same two mechanisms listed in Cryptographic primitives above. There is no third path.

🗺️ Operator SSO is planned and not implemented. This page previously carried a SAML/OIDC sign-in sequence against a hosted console. Neither exists: there is no SSO implementation anywhere in aa-api, aa-gateway, or aa-auth, and no console to sign in to. Treat identity federation as a design intent — see Open core boundary — not as an available control, and do not plan an IdP integration against it.

Secrets management

🗺️ The managed secret vault this section previously described does not exist. It claimed AES-256-GCM encryption at rest under a master key in a SaaS control-plane HSM, with rotation from a console. There is no AES-256-GCM implementation in the workspace crates, no HSM or KMS integration, and no console.

Do not treat this stack as a secret store. That advice is unchanged, but the precise state is narrower than “nothing ships” — and less reassuring:

• A store type exists and is mounted. There is a SecretsStore trait with one implementation, InMemorySecretsStore, wired into both the API and the gateway.
• It is always empty in a shipped build. Both production constructions instantiate it empty, and nothing can populate it: there is no registration route in the OpenAPI surface and no aasm secrets command. Every ${NAME} placeholder therefore resolves to UnknownPlaceholder and the request fails (HTTP 422 / gRPC FailedPrecondition).
• Where resolution does succeed, the caller receives the plaintext. The resolver substitutes ${NAME} tokens and returns the post-substitution arguments to the caller, rather than the gateway making the outbound call itself. The agent process ends up holding the raw credential. The audit entry records placeholder names only, so the credential is not written to the audit stream — but the agent has it.
• Nothing encrypts it. In-memory only, no encryption at rest, no key management.

So if you self-host, secrets reaching the gateway, proxy, or SDK are handled by whatever you supply them through — environment, file, or your own secret manager — and their protection is your deployment’s responsibility, not this software’s. Whether this surface is completed or removed is an open decision; this page describes only its current state.

Audit log

Policy decisions and agent-reported events are appended to a JSON Lines audit file, one line per entry. Database tables (audit_events, audit_logs) hold a mirror of those records for querying.

⚠️ One fixed file, not per-session files. The audit path names files {agent_id}-{session_id}.jsonl, but both shipped gateway serve paths pass the constants "gateway" and "default", so a real deployment produces a single gateway-default.jsonl that grows without bound. The per-session capability exists in the code and is never exercised in production. If you are planning retention, rotation, or per-tenant separation around per-session files, you will not get them. The properties below are stated precisely, because “immutable audit log” is a claim a security reviewer should be able to check rather than take on trust. All of it is verifiable against the Apache-2.0 agent-assembly source.

The JSONL file is hash-chained, and you can verify it yourself. Each entry carries a SHA-256 digest over its own fields plus the preceding entry’s digest (aa-core/src/audit.rs). An operator can check a file end to end with:

aasm audit verify-chain <path-to-session>.jsonl

which reports the number of entries verified, or fails naming the first bad index.

The chain is unkeyed, so bound what it proves. There is no log-signing key, no HMAC, no signature, and no external anchoring over audit records anywhere in the codebase. The chain detects casual or partial modification; it does not resist an actor who can rewrite the file, because that actor can recompute a fully valid chain. It also proves only that the entries present are internally consistent — not that every action produced one.

The database mirror carries no chain metadata. The runtime-to-storage conversion deliberately drops seq, previous_hash, and entry_hash, and neither audit_events nor audit_logs has a column for them. There is no verification routine that can run against either table — chain verification applies to the JSONL files only.

The log is append-only by convention, not by constraint. Retention pruning issues DELETE FROM audit_events against rows older than the cutoff in both the SQLite and Postgres drivers; a backfill migration has issued UPDATE against audit_logs; and the offline spill buffer evicts its oldest events when it hits its cap. There is no database trigger, revoked grant, or WORM setting preventing deletion or update, and the JSONL file is appended without fsync.

Emission is best-effort and decoupled from enforcement. Entries are handed to a bounded in-process channel with a non-blocking send; on backpressure the entry is dropped and the action proceeds anyway. A crash before flush loses whatever is still buffered. Budget debits emit no dedicated audit entry at all — the budget event types exist in the schema but are never constructed, so a debit is visible only via the surrounding decision entry, which is itself droppable. Absence of an entry is therefore not proof that an action did not occur.

A dropped entry is now distinguishable from tampering. The chain head only advances when an entry is actually written, so a drop leaves a visible sequence- number gap: verify-chain reports it as INCOMPLETE — hashes and links intact, some entries never arrived — separately from FAIL, which means an entry’s hash or its link to the previous entry doesn’t match (alteration or removal). Treat FAIL as “investigate a compromise” and INCOMPLETE as “investigate a capacity event”, not the other way around. The distinction has two residual gaps worth knowing: a tail loss (nothing written after it) and a prefix loss (nothing written before it, indistinguishable from a chain that legitimately resumed mid-sequence after a restart) both still read the same whether the cause was a drop or a deletion — an interior gap is where the distinction holds.

Retention is an operator-set policy, not a per-tenant setting. The storage drivers apply a retention policy that prunes rows past a configured age. This hub does not publish a default retention period or a per-plan retention figure — there is no managed service to enforce one.

Export is via the CLI, in three formats. aasm audit export --format <csv|json|jsonl> writes CSV, a JSON array, or JSON Lines; --format is required and has no default. A second command, aasm audit compliance-export, emits compliance-shaped records and can prepend a framework metadata header. JSONL is the format to prefer for a SIEM or a cold-storage archive, because each line parses independently and the stream appends without re-rendering.

There is no CEF output and no direct SIEM integration — feeding a SIEM means ingesting an exported file. See the core CLI docs for the full command surface.

Compliance posture

AI Agent Assembly holds no compliance certification, and no compliance assessment has been completed. No SOC 2, ISO 27001, or equivalent audit has been performed against the product or against a managed service. No Data Processing Agreement or Business Associate Agreement is available.

This section previously published a certification status table with a target date. There was no audit report, assessment scope, or executed legal template behind any row of it, so the table was removed rather than relabelled — a status table in a compliance section reads to a procurement reviewer as a programme with a trajectory, which is itself the claim.

What this page can tell a security reviewer is what the system does: the layered defense model, the STRIDE analysis, the cryptographic primitives actually in use, and the audit log’s real integrity properties — all documented above, and all verifiable against the Apache-2.0 source.

The SaaS claim publication checklist records what has to exist before any certification or legal-instrument claim is published here, and who must approve it.

Related documentation

• Why AI Agent Assembly? — competitive positioning and governance differentiation
• Managed control plane (design preview) — the managed control plane, which is planned and not available
• Open core boundary — what is in the Apache-2.0 core today vs. intended for the commercial tier
• Source of truth & status — the canonical maturity label for every area of this hub
• SaaS claim publication checklist — what must be evidenced before managed-service or compliance claims are published

Last reviewed: 2026-08-06 — AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Why AI Agent Assembly?

AI Agent Assembly is a governance layer for AI agents — a control that sits in the agent’s action path and enforces policy, tracks cost, and intercepts unsafe actions (unsafe tool calls, network egress, and budget overruns) before they execute. Think of it as a security checkpoint in front of each governed agent action — the tool calls your SDK wraps and the outbound requests routed through its proxy — not a dashboard that reports on actions after they happen. Which actions reach that checkpoint depends on how the agent is wired up and launched; see Known limitations. That category distinction is what this comparison is about.

This page helps readers see where AI Agent Assembly fits next to other tools in the AI governance and observability space. All competitor data is taken from each vendor’s public documentation as of 2026-05-05.

In short: most tools in this space observe what an agent did after the fact. AI Agent Assembly is built to enforce policy before an action runs. The sections below show where that difference matters, and where competitors are ahead.

Feature matrix

Because AI Agent Assembly is an enforcement control rather than a pure observability or monitoring tool, the rows below span both categories: the observability rows show that it still gives you the visibility those tools provide, while the policy-enforcement, access-control, and budget-enforcement rows show the security-checkpoint capabilities that monitoring-only tools do not have. Read the matrix with that framing — equal coverage on observability, decisive coverage on enforcement.

Each row is a capability. The columns are AI Agent Assembly (AAASM), Langfuse, Helicone, Opik, and Pillar Security.

Legend: ✓ = full support · partial = limited or gated behind a paid tier · ✗ = not available · n/a = not applicable to the product category.

🚧 Coming soon. Rows marked ✓ 🚧 in the AAASM column describe the AAA-Commercial (Enterprise) tier and the paid SaaS platform that delivers it — both are planned and not yet generally available. See Open core boundary for what ships today versus what is intended design.

Where we currently lag

These are capabilities competitors offer that AI Agent Assembly does not yet fully deliver.

1. Vault-backed secrets management — Pillar Security provides first-class secrets vault integration with automatic secret rotation and injection. AAASM currently supports secret-pattern detection via regex policies but does not integrate with HashiCorp Vault or AWS Secrets Manager.
2. Automated human-in-the-loop approval workflows — Pillar Security provides structured approval routing with escalation chains. AAASM can deny today (alert emission is planned, not yet shipped — see 🚧) and does not yet route decisions to a named approver queue.
3. Full-function self-hosted deployment — Langfuse, Opik, and Pillar Security offer a fully self-hostable product. AAASM self-hosting is limited-function today: a limited stack runs locally from the Apache-2.0 crates (Docker Compose) for evaluation and development, while the complete feature set is delivered via SaaS (see Open Core Boundary).
4. Evaluation frameworks and LLM-as-judge scoring — Langfuse and Opik provide built-in evaluation pipelines, dataset management, and automated LLM-as-judge scoring for output quality. AAASM’s policy engine operates on patterns and metadata, not semantic quality.
5. Prompt management and versioning — Langfuse provides a managed prompt registry with version history and A/B comparison. AAASM does not include a prompt registry.

Where we lead

These are capabilities where AI Agent Assembly is uniquely strong or differentiated.

1. Pre-execution runtime enforcement — AAASM is the only product in this comparison that makes binding allow/deny decisions before an agent action executes. All others are observability tools that record what happened after the fact.
2. Kernel-level bypass detection via eBPF — aa-ebpf reads TLS plaintext at the OpenSSL library level using Linux uprobes, surfacing bypass attempts that SDK-only solutions cannot see. It is a detection layer: the probes emit telemetry and return no verdict, so they report an action rather than preventing it, and they need a Linux host with an OpenSSL-linked process (the file-I/O kprobes additionally are x86_64-only). No competitor in this matrix offers kernel-level visibility at all.
3. Network-layer interception without agent code changes — aa-proxy performs MitM HTTPS interception using per-host certificates minted from a local root CA. Governance can be applied to agents that do not use the SDK, provided the agent process is launched so that it routes through the proxy and trusts that CA. No competitor supports sidecar-proxy-level enforcement.
4. Policy-as-code with GitOps workflow — AAASM policies are YAML/JSON documents that can be versioned, reviewed, and deployed via standard Git workflows. No competitor in this matrix offers a structured policy language; guardrails in other tools are typically configured through UI forms or proprietary DSLs.
5. Hash-chained, verifiable audit log — each entry in the per-session JSONL log carries a SHA-256 digest over its own fields plus the preceding entry’s digest, and aasm audit verify-chain re-walks that chain. This ships in the open-source build, not behind an Enterprise flag. Read the guarantee precisely, because compliance work (PCI-DSS, SOC 2 Type II) depends on the difference: the chain is unkeyed, so it detects accidental or careless alteration but is not a signature — anyone who can rewrite the log can recompute the chain. It covers the JSONL sink only; the database mirror stores no chain metadata. The log is append-only by convention, not by constraint — retention pruning deletes rows — and emission is best-effort, so a dropped entry is indistinguishable from tampering. See Audit log for the exact bounds. No competitor in this matrix offers a verifiable chain.

Competitor documentation references

Last validated 2026-05-05 against each vendor’s documentation as of that date.

Related documentation

• Security model — STRIDE threat model, IronClaw defense
• Open core boundary — what is OSS vs. enterprise
• Managed SaaS onboarding — design preview — planned, not available

Last reviewed: 2026-08-06 — AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

1. No change to your agent’s code, but the agent process must be launched so that it honours HTTP_PROXY/HTTPS_PROXY and trusts the proxy’s local root CA. On macOS the install is attempted at proxy start and shells out to security add-trusted-cert, which requires admin authorization — macOS prompts, and a refusal fails proxy startup. On Linux run sudo aasm proxy install-ca. Windows is unsupported. Interception is HTTP/1.1 only — HTTP/2, gRPC, and WebSocket are out of scope — and by default only the built-in LLM provider hosts are decrypted; other hosts are tunnelled uninspected unless you list them. ↩

2. Detection, not prevention: the probes emit telemetry and return no verdict, so an action they see is one that already happened. TLS visibility covers OpenSSL-linked processes only, and the layer requires Linux with a kernel that supports it, BTF, and a reachable loader daemon — the file-I/O kprobes additionally are x86_64-only. It degrades with a warning rather than failing closed if it cannot attach. ↩

3. Tamper-evident, not tamper-proof, and not immutable. Each entry in the per-session JSONL log carries a SHA-256 digest over its own fields plus the preceding entry’s digest; aasm audit verify-chain re-walks it. The chain is unkeyed — there is no HMAC, no signature and no external anchoring — so it detects careless or accidental alteration but not an attacker who can rewrite the file and recompute the chain. It covers the JSONL sink only; the database mirror stores no chain metadata. The log is append-only by convention rather than by constraint (retention pruning deletes rows), and emission is best-effort, so a dropped entry is indistinguishable from tampering. Full bounds in Audit log. ↩

Open core boundary

AI Agent Assembly follows an open-core model. The line is simple:

• Enforcement is open source. The interception mechanisms, policy engine, SDK shims, and CLI are Apache-2.0. Anyone can read, audit, and contribute to them.
• Enterprise operations are intended to be commercial. Capabilities such as SSO, SCIM, advanced audit, and multi-region data residency are planned for a commercial tier. That tier is not available, its licence terms are not published, and there is no paid plan to buy.

🗺️ The commercial side of this boundary is planned, not available. You can self-host a limited-function stack from the Apache-2.0 crates today — using the published Docker Compose example — for local evaluation and development. The managed service that is intended to deliver the commercial capabilities is not running; see Managed control plane (design preview) and Managed SaaS onboarding (design preview) for what that means in practice, and Source of truth & status for the canonical maturity label.

Why open core?

The enforcement path must be inspectable

The infrastructure that sits between AI agents and the outside world has to be trustworthy and independently auditable. Keeping the core open source is not a marketing choice — it follows directly from the security posture.

An enterprise cannot take our word for how the policy engine evaluates rules, how eBPF probes intercept system calls, or how the sidecar proxy terminates TLS. Open source means a third party can read, review, and verify the enforcement path without involving us.

A single boundary rule

The split between open and commercial follows one principle: enforcement is open; enterprise operations are commercial.

• If a feature controls what agents can do, it belongs in the Apache-2.0 core.
• If a feature controls how operators manage, scale, or audit the system at enterprise grade — identity federation, directory-driven user lifecycle, longer-retention and higher-assurance audit storage, regional deployment control — it belongs in the commercial tier.

A motivated team can fork, read, or contribute to the security controls listed as Apache-2.0 below, regardless of subscription status.

Open source strengthens the core

Open-sourcing the enforcement logic creates a community feedback loop. Security researchers who find a gap in the policy engine, proxy TLS handling, or an eBPF program can open an issue or send a pull request.

We chose Apache-2.0 specifically because it permits commercial integration without a copyleft obligation — SDK users can embed the shims in proprietary products without the license spreading to their own code.

Limited-function self-host today; managed service planned

Shipping the crates as open source lets teams read, audit, and contribute — and self-host a limited-function stack (via the published Docker Compose example) for local evaluation and development.

The enterprise-operations capabilities are intended to be delivered as a managed service rather than as self-managed software, because operating a multi-tenant platform takes infrastructure and on-call capability that a self-managed install does not get for free. That is a design intent, not a shipped service: the managed platform is not running, and this hub publishes no availability, support, or compliance commitment for it.

What is in the Apache-2.0 core today

These ship in the public agent-assembly monorepo and the three SDK repos, under Apache-2.0 (the python-sdk shim is MIT — see crate licensing). They run without any managed service.

The public issue trackers and pull-request queues on github.com/ai-agent-assembly are open to anyone. They are not a support channel with a response commitment.

What is intended for the commercial tier

🗺️ Planned — not available. Everything in this section is design intent. The commercial tier is not for sale, its licence terms are not published, and the managed service that would deliver it is not running. This is not a roadmap commitment, a delivery date, or an offer.

Identity federation, directory-driven user provisioning, longer-lived and higher-assurance audit storage, audit export into external security tooling, and regional deployment control are the capability areas intended to sit on the commercial side of the boundary — because they are operator-management concerns rather than enforcement controls.

This hub deliberately does not publish, for any of them: a plan or tier they belong to, a price, a quota, a retention period, a region list, a data-residency guarantee, an availability or support commitment, or a compliance certification. The SaaS claim publication checklist records what has to be evidenced, and by whom, before any of that can be published.

Crate licensing

All Cargo crates in the agent-assembly workspace are Apache-2.0:

The three SDK native-binding shims are not members of the agent-assembly Cargo workspace — each lives in its own SDK repo and carries that repo’s own license:

Apache 2.0 key terms

The Apache License 2.0 grants users the right to use, reproduce, prepare derivative works, distribute, and sublicense the software with or without modification. It does not grant trademark rights, and it requires preservation of copyright notices and attribution in distributed works. See the full license text at https://www.apache.org/licenses/LICENSE-2.0.

The commercial capabilities described above are intended to be delivered by the managed control plane rather than by separate closed-source crates, so the boundary is a deployment boundary rather than a second licence over the enforcement path. The interception and enforcement logic listed in What is in the Apache-2.0 core today is Apache-2.0.

Contributing to the OSS core

The Apache-2.0 crates welcome community contributions. See CONTRIBUTING.md in the agent-assembly repository for:

• Branching and commit conventions
• How to run the test suite (cargo nextest run --workspace)
• The CLA requirement for non-trivial contributions
• How to file issues and feature requests

Requests for the capabilities intended for the commercial tier are tracked internally by the AI Agent Assembly team. Filing one is not a delivery commitment.

Related documentation

• Security model — cryptographic primitives and audit log details
• Managed control plane (design preview) — the managed control plane, which is planned and not available
• Source of truth & status — the canonical maturity label for every area of this hub
• SaaS claim publication checklist — what must be evidenced before commercial-tier claims are published
• Why AI Agent Assembly? — open-source posture vs. competitors

Last reviewed: 2026-08-06 · AI Agent Assembly Team

This page describes a licensing and deployment boundary. It is not legal advice and it is not a licence grant beyond the Apache-2.0 terms of the published crates. Commercial-tier licence terms are not published; nothing here creates one.

Last updated: 2026-09-07 by AI Agent Assembly Team

FAQ

Answers to the questions first-time visitors ask before reading any of the detailed pages. Each answer links to where the topic is covered in full.

What is AI Agent Assembly, in one sentence?

It is a governance layer for AI agents: it sits between your agents and the outside world and enforces policy, tracks cost, and intercepts unsafe actions before they run. See the Introduction and Why AI Agent Assembly?.

Do I have to change my agent’s code?

Not necessarily. Three interception mechanisms exist, they are deployed independently rather than as an ordered pipeline, and you can pick how invasive to be:

• The SDK layer needs a small amount of instrumentation in your code and is the fastest path.
• The sidecar proxy (aa-proxy) governs an agent’s network traffic without modifying the agent’s own source, on traffic that is routed to it and trusts its CA.
• The eBPF sensor (aa-ebpf, Linux only) observes activity at the kernel level and reports it. It is observe-only: it returns no verdict and blocks nothing.

See the interception mechanisms in the Introduction.

Does it work with my LLM / framework?

Yes — it is provider-agnostic. It governs agents regardless of which model provider you use, and ships SDKs for Python, TypeScript/Node, and Go, with framework examples (LangChain, LlamaIndex, bare OpenAI, and more) in the examples repository.

Is it free? What is open source vs. paid?

The enforcement core — the interception mechanisms, policy engine, SDKs, and CLI — is open source under Apache-2.0. Enterprise operations (SSO, SCIM, tamper-evident audit, dedicated regions, SLAs) are commercial and delivered on paid SaaS tiers. See the Open core boundary.

Can I self-host it?

You can self-host a limited-function stack from the open-source crates (using the published Docker Compose example) for local evaluation and development. The complete feature set is delivered through the AI Agent Assembly cloud (SaaS). See the Open core boundary.

How does it actually block an unsafe action?

Before an agent action runs, the gateway evaluates your policy and returns an allow or deny decision; a deny stops the action. Budgets are enforced the same way — once a team is over budget, further calls are denied. See the Policy reference.

How is it different from an observability / tracing tool?

Observability tools record what an agent did, after the fact. AI Agent Assembly makes a binding allow/deny decision before the action executes. The comparison page maps this against other tools.

Where do I get started right now?

Clone the examples repository and run a governed agent end to end — that is the path you can run today. The managed service is planned and not available.

What do the acronyms mean (eBPF, SCIM, mTLS, STRIDE…)?

See the Glossary, which defines every recurring term and acronym in plain language.

Last updated: 2026-09-07 by AI Agent Assembly Team

Managed SaaS onboarding — design preview

🗺️ Design preview — planned, not available. The AI Agent Assembly managed SaaS platform has no public signup, no published plans or prices, and no service commitments. Nothing on this page is purchasable or usable today, and nothing here is an offer, a quote, or a contractual commitment.

This page is for readers evaluating whether to wait for a managed workspace or to start on the open-source stack now. It deliberately does not contain onboarding steps.

An earlier version of this page walked through managed-workspace onboarding: tier selection, quotas, region selection, console screens, credential issuance, support channels, procurement, and legal-agreement handling. Those instructions described a service that is not running, so they were removed rather than restated in vaguer language. The SaaS claim publication checklist records each removed claim, the owner who must approve restoring it, and the evidence that approval requires.

For the canonical maturity and visibility label of every area of this hub — including Cloud — see Source of truth & status.

What you can run today

The open-source stack is what ships. It is Apache-2.0, public, and versioned as v0.0.1-rc (see the compatibility matrix for the exact component versions that work together).

The self-hostable stack is limited-function and intended for local evaluation and development. Open core boundary describes which capabilities are in the open-source core and which are intended for the commercial tier.

The onboarding journey this is designed for

Everything in this section is design intent. It names no plan, price, quota, region, retention period, console screen, tenant-identifier format, availability commitment, or date, because none of those exist — see what this page does not publish.

The managed service is intended to deliver the operator-management capabilities that sit on the commercial side of the open core boundary: identity federation, directory-driven user provisioning, longer-lived and higher-assurance audit storage, audit export into external security tooling, and regional deployment control. The enforcement path itself is Apache-2.0 and needs none of them.

The dependency that shapes the whole journey: enforcement does not wait on the control plane. A team adopting the managed service later runs the same gateway, policy engine, proxy and SDK shims it runs today; the managed service is intended to add operator management around them, not to replace them. That is why the available path above is not a stopgap.

What this page does not publish, and why

The managed service is not running, so this hub does not publish:

• Plan or tier names, prices, or what any plan includes.
• Agent, policy, or retention quotas.
• Regions, region selection, or data-residency guarantees.
• Availability, uptime, or support-response commitments.
• Billing, invoicing, purchase-order, or procurement-timeline instructions.
• Onboarding steps that reference a console, signup form, or credential screen.
• Compliance certifications, or the availability of a DPA or BAA.

Each of these is tracked in the publication checklist with the evidence needed to publish it. Publishing any of them before that evidence exists would misrepresent the product.

What must be true before any of this is published

This hub does not decide when a planned area becomes available; the SaaS claim publication checklist does, one claim class at a time. Each register row names the evidence required and the approval owner who must sign the specific wording.

Two things gate the whole page rather than one row: the managed service running and carrying real traffic, and the status map moving this area off 🗺️ Planned. Until both hold, no register row can be satisfied, because every one of them requires evidence produced by a running service.

Evidence

• Maturity: Source of truth & status’s Operations (running & onboarding) row — 🗺️ Planned.
• Claim record: this page’s AA-PAGE-META carries a single ADR 0033 §6 Planned claim, with platforms: [] and no availability value — the metadata form for a capability present in no published artifact.
• Removed claims and their restoration conditions: the publication checklist register.
• There is no implementation to link: the cloud repository is private and outside this hub’s public content boundary. A design deep-dive here would describe a system no reader can verify.

Related documentation

• Source of truth & status — which areas ship today and which are planned
• Open core boundary — the open-source / commercial split
• Managed control plane — design preview — planned, not available
• SaaS claim publication checklist — what must be evidenced before managed-service claims return

Last reviewed: 2026-09-07 · AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Managed control plane — design preview

🗺️ Design preview — planned, not available. The AI Agent Assembly managed control plane (Cloud) is not running. There is no workspace to provision, no console to log into, and no service, support, or compliance commitment attached to it. Nothing on this page is an offer or a contractual commitment.

This page is for enterprise platform, security, and procurement readers who need to know what the managed control plane does not yet provide, so they can plan against the open-source stack instead of against an unavailable service.

An earlier version of this page documented the managed platform as if it were operating: a region list with data-residency guarantees, tenant provisioning paths, per-tier quotas, SSO and SCIM configuration walkthroughs, a console budget form, an availability-and-support SLA table, card and invoice billing setup, and the handling of Data Processing Agreements and Business Associate Agreements. None of those had a running service, an approved commercial policy, or a legal review behind them, so they were removed rather than reworded into softer promises.

Every removed claim is listed in the SaaS claim publication checklist, together with the owner who must approve restoring it and the evidence that approval requires. Source of truth & status carries the canonical maturity label for Cloud and for every other area of this hub.

What runs today instead

Governance enforcement is open source and does not depend on the managed control plane. The gateway, the policy engine, the sidecar proxy, the eBPF sensor, the SDK shims, and the aasm CLI are Apache-2.0 and can be run locally.

The console budget form this page previously described did not match the budget schema the gateway actually validates against. Policy reference is the source of truth for budget behaviour.

The control-plane design this is intended for

Everything in this section is design intent. It names no region, tenant format, quota, plan, price, SLA, or date, because none of those exist — see what this page does not publish.

The managed control plane is intended to add the operator-management capabilities that sit on the commercial side of the open core boundary: identity federation, directory-driven user provisioning, longer-lived and higher-assurance audit storage, audit export into external security tooling, and regional deployment control. The reason managed delivery is the intent rather than a self-managed distribution of the same code: multi-tenant infrastructure and on-call operation are what a self-managed install does not get for free.

The dependency that shapes the design: enforcement does not wait on the control plane. The gateway, policy engine, proxy, and SDK shims a team runs today are the same ones a managed workspace would run underneath — the control plane is intended to add operator management around them, not to replace them.

What this page does not publish, and why

Because the managed control plane is not running, this hub does not publish:

• Regions, region selection, or data-residency guarantees.
• Tenant or workspace provisioning steps, or a tenant-identifier format.
• Plan or tier names, prices, or per-tier quotas for agents, policies, or audit-log retention.
• SSO (SAML 2.0 / OIDC) or SCIM 2.0 configuration instructions, endpoints, or supported-operation matrices.
• A console role model, or group-to-role mapping instructions.
• Availability, uptime, or support-response commitments, or service credits.
• Billing, invoicing, payment-method, purchase-order, or payment-terms instructions.
• Compliance certifications, or the availability of a DPA or a BAA.

Publishing any of these before the corresponding service, owner approval, and evidence exist would present an unavailable service as a defined one. The publication checklist names the evidence required for each.

What must be true before any of this is published

This hub does not decide when a planned area becomes available; the SaaS claim publication checklist does, one claim class at a time. Each register row names the evidence required and the approval owner who must sign the specific wording.

Two things gate the whole page rather than one row: the managed control plane running and carrying real tenants, and the status map moving this area off 🗺️ Planned. Until both hold, no register row can be satisfied, because every one of them requires evidence produced by a running service.

Evidence

• Maturity: Source of truth & status’s Cloud (SaaS control plane) row — 🗺️ Planned.
• Claim record: this page’s AA-PAGE-META carries a single ADR 0033 §6 Planned claim, with platforms: [] and no availability value — the metadata form for a capability present in no published artifact.
• Removed claims and their restoration conditions: the publication checklist register.
• There is no implementation to link: the cloud repository is private and outside this hub’s public content boundary. A design deep-dive here would describe a system no reader can verify.

Related documentation

• Source of truth & status — which areas ship today and which are planned
• Managed SaaS onboarding — design preview — managed onboarding, also planned
• Open core boundary — the open-source / commercial split
• Security model — the security posture of the open-source enforcement path
• SaaS claim publication checklist — what must be evidenced before managed-service claims return

Last reviewed: 2026-09-07 · AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Choose your SDK

Pick the SDK for the language your agent is already written in; this page hands you to that SDK’s own documentation, which is where every install step and API surface lives.

Choose your language

Each SDK is a separately versioned program with its own documentation site and its own version selector.

Prefer reading working code first? The runnable examples carry end-to-end walk-throughs for all three languages.

Two different words spelled the same way

The Documentation-area maturity column above is the maturity of a documentation area, read from the status map, which defines what each label means. That page owns the definitions and this one does not restate them.

It is not a statement about what happens to one of your agent’s actions. That is a separate vocabulary, defined once in ADR 0033 §6, and this page makes no claim in it. Verify is the page that maps a published sentence onto that vocabulary.

Before you choose

Choosing a language is not the same decision as choosing where a decision about an action is made, and the second one is made before this page rather than on it. It is an evaluation decision: Choose your enforcement path is where it is made, and Evaluate carries the default posture.

What this page does not do

This page is a router, and it is deliberately thin:

• It does not carry install steps or an API surface. Those belong to each SDK’s own documentation, which is the canonical source for them, and duplicating them here is how the copies drift apart.
• It does not describe a mechanism. What a given component does with an action is documented at depth in the core documentation.
• It does not cover running the stack. That is Operate.
• It does not cover checking a published statement. That is Verify.

Going deeper

The contract every SDK speaks to, and the components behind it, are documented in the core documentation.

Last updated: 2026-08-13 by AI Agent Assembly Team

Run and diagnose

This section routes you through running the stack on a host you control, from starting an agent under it to working out why an expected control did not fire; the commands and configuration themselves live in the pages linked below.

The four questions, in order

Most operator sessions are one of these four, and they are ordered because each one assumes the previous is already true.

Question 1 is first for a reason: what reaches a checkpoint at all depends on how the agent was launched, so an agent started outside that path is a common answer to question 4.

Before you start

Which components you need, and which versions of them work together, are two different lookups and both are in Reference:

• Compatibility matrix pairs versions across components.
• Status map says who owns each area and how mature its documentation is.
• Choose your enforcement path says which governed paths exist, what each one needs on a host, and what each one does not cover.

The managed service is not an operating route today

The Cloud area is marked 🗺️ Planned in the status map, on the documentation-area axis. There is no managed service to operate from this section, and the two pages that discuss one (Managed SaaS onboarding (design preview) and Managed control plane (design preview)) sit in Evaluate, where their reader is someone deciding what to tell a stakeholder rather than someone running it.

Those pages move into this section when, and only when, their area’s Maturity cell in the status map stops reading 🗺️ Planned. That is a string comparison against a generated table, not a judgement any page may make on its own.

What this page does not do

• It does not describe a mechanism. What each component does with an action is documented at depth in the core documentation.
• It does not restate a command or a configuration key. Those belong to the pages in the table above.
• It does not cover adding a checkpoint to code you are writing. That is Integrate.
• It does not cover checking a published statement against its evidence. That is Verify.

Going deeper

The components, their configuration and their behaviour are documented in the core documentation.

Last updated: 2026-09-07 by AI Agent Assembly Team

Docker & Containers

This page is the reference for running AI Agent Assembly from published container images — which images exist, how they are tagged, how to pull and run the gateway and runtime, how to build your own agent image on top of the SDK base images, and how to wire the governed agent + sidecar + gateway topology so it works out of the box.

Scope: this covers the limited-function OSS self-host stack, not the managed SaaS. The Apache-2.0 images below let you stand up the enforcement data plane locally for evaluation and development. Full functionality — team budgets, the central registry, the operator dashboard, persistence, SSO/SCIM — remains SaaS-only. See Open core boundary for the split and Managed control plane (design preview) for the managed platform. This is not a production orchestration guide (no Helm / Terraform / Kubernetes).

Published images

Five images are published to the GitHub Container Registry under ghcr.io/ai-agent-assembly. All are multi-arch (linux/amd64 + linux/arm64) and carry SLSA build provenance (see Provenance & verification).

Not published as images. aa-api (the REST/OpenAPI surface) and aa-proxy (the egress-interception proxy) are Apache-2.0 crates in the agent-assembly repository but have no published container image — do not expect to docker pull them. There is no separately runnable aa-api container: the REST surface (/api/v1/health) is only exposed when the gateway is launched in local mode (--mode local), a single-process dev topology not used by the gateway + runtime container stack on this page — that stack runs the gateway in its default legacy gRPC mode, which serves gRPC only on :50051 and no HTTP (see Self-Host Observability). To run aa-proxy, build it from source (aa-proxy/Dockerfile).

Image tags

The two service images and the three SDK base images use different tag schemes — the difference is deliberate and easy to get wrong.

Service images (aa-gateway, aa-runtime) are tagged with the release version plus a moving latest:

ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6   # immutable release tag
ghcr.io/ai-agent-assembly/aa-gateway:latest        # moves with each release

SDK base images (python, node, go) are tagged <runtime>-<version> — the runtime version is part of the tag, so there is no bare :v0.0.1-rc.6 tag on these images. Each also publishes a moving, versionless <runtime> tag and latest:

For reproducible builds, pin the release-tagged variant (or, better, a @sha256 digest — see Provenance & verification). Use latest only for throwaway local demos.

Pull and run the gateway and runtime

Pull

docker pull ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6
docker pull ghcr.io/ai-agent-assembly/aa-runtime:v0.0.1-rc.6

Both images are public — no docker login is required to pull.

Run the gateway

The gateway loads a policy file and serves gRPC. Mount your policy and publish :50051:

docker run --rm \
  -v "$PWD/policy.yaml:/etc/aa/policy.yaml:ro" \
  -p 50051:50051 \
  ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6 \
  --policy /etc/aa/policy.yaml --listen 0.0.0.0:50051

Run the runtime

The runtime owns the SDK IPC socket (on a shared volume) and its health/metrics server. Point it at the gateway with AA_GATEWAY_ENDPOINT:

docker run --rm \
  -e AA_AGENT_ID=my-agent-001 \
  -e AA_GATEWAY_ENDPOINT=http://gateway-host:50051 \
  -v aa-runtime-socket:/tmp \
  -p 8080:8080 \
  ghcr.io/ai-agent-assembly/aa-runtime:v0.0.1-rc.6

Health-checking

curl -fsS http://localhost:8080/ready       # runtime readiness -> "ready"
curl -fsS http://localhost:8080/health      # runtime liveness (JSON)
curl -fsS http://localhost:8080/metrics     # Prometheus scrape target

Probing the gateway. As launched here (--policy … --listen 0.0.0.0:50051, no --mode), the gateway runs in legacy gRPC mode: it serves gRPC only on :50051 and exposes no HTTP health endpoint — there is no /healthz to curl on this container. On top of that the image is distroless (no shell, no curl/wget inside), so a Compose healthcheck: ["CMD-SHELL", …] cannot run inside it either. Probe it from the host with a TCP connect to the gRPC port :50051 instead. A standard gRPC grpc.health.v1.Health service on :50051 is being added (AAASM-4759); until it ships, a TCP-level check of :50051 is the gateway liveness signal.

See Self-Host Observability for the full health, readiness, and Prometheus-metrics surface, including the baseline metric set.

Compose

The minimal runtime-sidecar stack as a Compose snippet:

services:
  aa-runtime:
    image: ghcr.io/ai-agent-assembly/aa-runtime:v0.0.1-rc.6
    environment:
      AA_AGENT_ID: "my-agent-001"
      AA_POLICY_PATH: "/etc/aa/policy.toml"   # local enforcement, no gateway
    volumes:
      - aa-runtime-socket:/tmp                # socket lives at /tmp/aa-runtime-my-agent-001.sock
      - ./policy.toml:/etc/aa/policy.toml:ro
    ports:
      - "8080:8080"                           # health + metrics

volumes:
  aa-runtime-socket:

A complete, runnable version — plus the optional aa-proxy egress profile — is maintained in the examples repository at scenarios/live-core-enforcement/.

Build your own agent image

The python, node, and go images are base images: the language runtime with the Agent Assembly SDK (and the aasm CLI) already installed. Build your agent by adding only your source on top — no SDK install step needed.

# Python agent on the SDK base image.
FROM ghcr.io/ai-agent-assembly/python:3.13-slim-v0.0.1-rc.6

WORKDIR /agent
COPY agent.py /agent/agent.py

# The base image already provides `python`, the `agent_assembly` SDK
# (native extension included), and the `aasm` binary — so no `pip install`.
CMD ["python", "/agent/agent.py"]

The Node and Go base images work the same way — swap the FROM line for ghcr.io/ai-agent-assembly/node:22-slim-v0.0.1-rc.6 (a bare require('@agent-assembly/sdk') resolves via the base image’s NODE_PATH) or ghcr.io/ai-agent-assembly/go:1.26-alpine-v0.0.1-rc.6 (the go-sdk is already in the module cache). Reference Dockerfiles for all three languages live in the agent-assembly repository under docker/smoke/agents/.

The governed topology

For per-tool allow/deny enforcement, run the full three-piece topology: your agent, the aa-runtime sidecar, and the aa-gateway. The runtime’s own local policy is a coarse action-type denylist; only the gateway’s section-based policy engine can distinguish, say, read_file (allow) from delete_file (deny).

flowchart LR
  agent["your agent<br/>(SDK)"]
  runtime["aa-runtime<br/>sidecar"]
  gateway["aa-gateway<br/>(policy authority)"]

  agent -- "register (gRPC :50051)" --> gateway
  agent -- "check (UDS /tmp/…​.sock)" --> runtime
  runtime -- "CheckAction (gRPC :50051)" --> gateway

Two distinct transports are in play: registration is a direct SDK → gateway gRPC call (the native client reads AA_GATEWAY_ENDPOINT, which defaults to 127.0.0.1:50051 — wrong inside a container, so set it explicitly); the governed check goes over the runtime’s Unix domain socket, and the runtime forwards CheckAction to the gateway.

The uid requirement

The runtime creates its IPC socket owner-only (0600) — there is no group/world access window (a tightened umask guarantees 0600 from the first instant, closing a TOCTOU gap). Both aa-runtime and aa-gateway run as the distroless non-root user, uid 65532. Because the socket is 0600, the agent process must run as the same uid (65532) as the runtime — otherwise it cannot open the socket and every governed call fails to connect. Aligning the uid is what makes the stack work out of the box:

services:
  aa-gateway:
    image: ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6
    command: ["--policy", "/etc/aa/policy.yaml", "--listen", "0.0.0.0:50051"]
    volumes:
      - ./policy.yaml:/etc/aa/policy.yaml:ro
    ports:
      - "50051:50051"

  aa-runtime:
    image: ghcr.io/ai-agent-assembly/aa-runtime:v0.0.1-rc.6
    depends_on: [aa-gateway]
    environment:
      AA_AGENT_ID: "my-agent-001"
      AA_GATEWAY_ENDPOINT: "http://aa-gateway:50051"
    volumes:
      - aa-runtime-socket:/tmp
    ports:
      - "8080:8080"

  agent:
    build: ./agent
    # Align the agent's uid with the runtime's (distroless nonroot = 65532)
    # so it can open the 0600 runtime socket. Without this the governed
    # calls cannot connect.
    user: "65532:65532"
    depends_on: [aa-gateway, aa-runtime]
    environment:
      AA_AGENT_ID: "my-agent-001"                     # MUST match aa-runtime
      AA_RUNTIME_SOCKET: "/tmp/aa-runtime-my-agent-001.sock"
      AA_GATEWAY_ENDPOINT: "http://aa-gateway:50051"  # native client (registration)
      AA_GATEWAY_URL: "http://aa-gateway:7391"        # SDK gateway handle (REST control plane)
    volumes:
      - aa-runtime-socket:/tmp                          # same socket the runtime created

volumes:
  aa-runtime-socket:

Distroless images have no in-container healthcheck. Because aa-runtime and aa-gateway ship no shell, gate readiness from the host (poll the runtime’s :8080/ready and the gateway’s :50051) rather than with a Compose CMD-SHELL healthcheck — an in-container probe fails with exec: "/bin/sh": no such file or directory and leaves depends_on: condition: service_healthy stuck.

Fail-closed behavior

The governed path is fail-closed. Under enforcement_mode="enforce" a gateway deny blocks the tool call before it runs. Critically, an unreachable dependency is treated as a deny, not as an allow: if the agent cannot reach its runtime sidecar — or the runtime cannot reach the gateway — the SDK denies the action rather than letting it execute ungoverned. This is why the uid alignment and endpoint wiring above matter: a mis-wired socket or gateway endpoint surfaces as blocked calls, not as silent bypass.

Where a specific SDK’s fail-closed-on-unreachable default is still being finalized, that is tracked under AAASM-4766 / AAASM-4760; the enforcement contract documented here is the intended behavior of the governed topology.

A complete, genuine end-to-end version of this topology — real SDK, real runtime, real gateway, a policy that actually blocks a delete_file call — is maintained in the examples repository at scenarios/live-core-enforcement/.

Provenance & verification

Every published image is built multi-arch with SLSA build provenance attached as an in-toto attestation, so you can verify how and from where an image was built before you run it.

Inspect the provenance of an image (and its multi-arch manifest) with BuildKit’s imagetools:

docker buildx imagetools inspect \
  ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6 \
  --format '{{ json .Provenance }}'

Pin by immutable digest. Tags (even release tags) are convenient but a digest is content-addressed and cannot be moved. Resolve the current digest:

docker buildx imagetools inspect ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6
# Name: ghcr.io/ai-agent-assembly/aa-gateway:v0.0.1-rc.6
# Digest: sha256:9754356e4d9b6062b0bc3b40fde62c196112636ee11650fb6e4cee91ae428954

…then pin it in your docker run / Compose / Dockerfile:

ghcr.io/ai-agent-assembly/aa-gateway@sha256:9754356e4d9b6062b0bc3b40fde62c196112636ee11650fb6e4cee91ae428954
ghcr.io/ai-agent-assembly/aa-runtime@sha256:5b604612b80f14a1763cc50d126a31ee05454af874bd8a4c3d3cf6fe6c444b74

(The digests above are the v0.0.1-rc.6 manifests at the time of writing — always re-resolve for the version you intend to run.)

Non-root posture. The aa-gateway and aa-runtime images are built on gcr.io/distroless/static:nonroot — they contain only the statically linked binary (no shell, no package manager) and run as uid 65532 by default, minimizing attack surface.

SBOM and image signatures are a tracked follow-up (AAASM-4762). Once published, this section will document verifying the SBOM attestation and the image signature; until then, provenance inspection and digest pinning above are the available verification steps.

Support boundary

The container images on this page stand up the limited-function OSS self-host stack — the enforcement data plane (runtime + gateway + optionally aa-proxy, built from source) — for local evaluation and development. You are responsible for operating and monitoring what you self-host.

Full functionality is SaaS-only: team budgets, the central agent registry, the operator dashboard, persistence, identity federation (SSO/SCIM), regional data residency, and tamper-evident audit are intended for the managed AI Agent Assembly cloud — planned, not available. See Open core boundary for the precise line between what you can self-host and what the SaaS adds.

Related documentation

• Self-Host Observability — health, readiness, and Prometheus metrics for the images above.
• Open core boundary — OSS vs SaaS feature split and crate licensing.
• Managed control plane (design preview) — the managed SaaS platform.
• Security model — the interception mechanisms and defense-in-depth posture.
• Troubleshooting — common issues when running the stack.

Last reviewed: 2026-07-18 · AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Self-host observability

This page is for operators and SREs running the limited-function OSS stack — the self-hostable Apache-2.0 crates you can bring up locally (via the published Docker Compose example) for evaluation and development. It answers the operator’s first question — “can I monitor what I run?” — by showing where the shipped binaries expose their liveness/readiness probes and their Prometheus metrics, so you can wire up a health check and a scrape target without reading the Rust source.

Scope: this is the limited-function self-host stack. There is no availability, on-call, or compliance commitment from anyone — not for a stack you self-host, and not for the managed control plane, which is planned and not available. Self-hosting is intended for local evaluation and development; you are responsible for operating and monitoring it. This page documents the observability surface the OSS binaries already expose; it is not a production deployment or orchestration guide (no Helm / Terraform / Kubernetes).

What the stack exposes

The self-hostable stack runs two binaries with a published container image — aa-runtime and aa-gateway (see Docker & Containers). They do not expose the same surface: only aa-runtime serves HTTP health/metrics (on :8080). As launched in the container topology (--policy … --listen 0.0.0.0:50051, no --mode), the gateway runs in legacy gRPC mode and serves gRPC only on :50051 — it exposes no HTTP /healthz and no /api/v1/health. Those HTTP surfaces exist only when the gateway is started in a different mode: /healthz in local or remote mode, and /api/v1/health in local mode only (--mode local, a single-process dev topology this container stack does not use, and which has no separately runnable aa-api container).

The gateway’s HTTP /healthz and /api/v1/health surfaces are not part of the container topology on this page — they appear only when the gateway is launched in a non-default mode, summarized below:

The rest of this page covers each surface and gives copy-paste probe and scrape examples.

Health and readiness probes

aa-runtime — /health and /ready

The runtime runs a combined health/metrics HTTP server bound to AA_METRICS_ADDR (see Metrics endpoint below for the env var and its default). It serves two probe routes:

• GET /health — liveness. Returns 200 OK with a JSON body reporting status, process uptime, events processed, and which enforcement layers are active or degraded. Use this as a liveness probe.
• GET /ready — readiness. Returns 200 OK (body ready) once the runtime is ready to accept work, or 503 Service Unavailable (body not ready) before then. Use this as a readiness/startup gate.

$ curl -fsS http://localhost:8080/health
{"status":"healthy","uptime_secs":42, ...}

$ curl -fsS http://localhost:8080/ready
ready

aa-gateway — TCP liveness on :50051

In the container topology the gateway runs in legacy gRPC mode (--policy … --listen 0.0.0.0:50051, no --mode). In that mode it serves gRPC only and exposes no HTTP health endpoint — there is no /healthz to curl. Gate its liveness with a TCP connect to the gRPC port :50051 from the host (the aa-gateway image is distroless, so an in-container CMD-SHELL probe cannot run either — see Docker & Containers).

# TCP-level liveness — succeeds once the gateway is accepting gRPC connections.
$ nc -z localhost 50051 && echo "gateway up"
gateway up

A standard gRPC grpc.health.v1.Health service on :50051 is being added (AAASM-4759); until it ships, the TCP check above is the gateway liveness signal for the container topology.

HTTP health (/healthz, /api/v1/health) — local/remote mode only

The gateway does serve HTTP health endpoints, but only when launched in a non-default mode — not in the legacy-gRPC container topology on this page:

• GET /healthz — process-liveness in local and remote mode. Returns 200 OK with a small JSON body (e.g. {"mode":"local","version":"...","storage":"sqlite","uptime_secs":...}).
• GET /api/v1/health — REST API health in local mode only (--mode local), mounted by the same aa-gateway process (there is no separate aa-api container). Returns 200 OK when every subsystem check passes, or 503 Service Unavailable when any is degraded; the JSON body includes the build version, api_version, uptime, and a checks map for the policy engine, registry, audit, and alerts.

Local mode is a single-process dev topology, not the gateway + runtime container stack documented in Docker & Containers; its HTTP port comes from that mode’s own configuration rather than the --listen gRPC address.

Prometheus metrics endpoint

The aa-runtime health/metrics server exposes a Prometheus text-format scrape endpoint.

AA_METRICS_ADDR is the single environment variable that controls this server’s bind address; the same server serves /health, /ready, and /metrics. Set it to change the interface or port, e.g. AA_METRICS_ADDR=127.0.0.1:9090 to bind loopback only. (0.0.0.0 is a bind address — point your scraper at a routable host/IP for the runtime, not at 0.0.0.0.)

$ curl -fsS http://localhost:8080/metrics
# Prometheus text exposition format
aa_events_received_total 0
aa_events_emitted_total 0
...

Baseline metrics

The runtime pre-registers six baseline metrics at 0 on startup, so the /metrics surface is stable from the very first scrape (a metric never “appears late” the first time it is incremented). The names and types below are taken directly from the runtime source; the “What it represents” column is explanatory (the source registers names and types only, without HELP text). Additional metrics may appear as the runtime does work.

Note: these six are the baseline surface. Only aa_active_connections and aa_channel_utilization_ratio are gauges; the other four are counters. None are histograms. Because they start at 0, an all-zero scrape shortly after startup is expected, not a sign of a broken exporter.

Minimal scrape configuration

Point a Prometheus server at the runtime’s metrics endpoint. A minimal prometheus.yml scrape job:

scrape_configs:
  - job_name: aa-runtime
    metrics_path: /metrics
    static_configs:
      - targets: ["<runtime-host>:8080"]   # matches AA_METRICS_ADDR's port

Replace <runtime-host> with the address where the runtime is reachable (for the Docker Compose example, the runtime service’s name/port on the compose network). If you override AA_METRICS_ADDR, update the target port to match.

For a liveness/health check outside Prometheus, probe the runtime’s /health over HTTP (curl -f gates on its non-200 status) and check the gateway with a TCP connect to :50051 (nc -z) — in the container topology the gateway serves no HTTP health endpoint. The HTTP /healthz / /api/v1/health probes apply only if you run the gateway in local/remote mode, as noted above.

Where to confirm these details

These endpoints live in the Apache-2.0 crates in the agent-assembly repository, so you can verify them against the source you run:

• aa-runtime/src/config.rs — AA_METRICS_ADDR and its default.
• aa-runtime/src/runtime.rs and aa-runtime/src/health/ — the health/metrics server and the baseline metrics.
• aa-gateway/src/main.rs — the mode resolver (resolve_mode); the default is legacy-grpc, which runs serve_tcp (gRPC only, no HTTP health) unless --mode/AA_MODE selects local or remote.
• aa-gateway/src/routes/healthz.rs — the /healthz liveness probe (local and remote modes only).
• aa-api/src/routes/health.rs — the /api/v1/health check (mounted by the gateway in local mode; there is no separately runnable aa-api container).

Related documentation

• Open core boundary — what is in the Apache-2.0 core today vs. intended for the commercial tier.
• Managed control plane (design preview) — the managed control plane, which is planned and not available.
• Security model — the Telemetry layer and the broader defense-in-depth posture.
• Troubleshooting — common issues when running the stack.

Last reviewed: 2026-07-18 · AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Troubleshooting

This page is a starting point when something is not working the way the docs describe. It is for operators and developers who have already read the Docker Compose quickstart or an SDK page and hit a specific problem.

Because AI Agent Assembly is composed of five independently versioned programs (core, three SDKs, and Arena), most concrete runtime symptoms are covered in the owning component’s own troubleshooting section. This page routes you to the right one and lists cross-cutting issues that don’t belong to a single component.

Common first-run failures

If you are evaluating AI Agent Assembly for the first time, these are the symptoms newcomers hit most often — each with the exact fix. If your symptom isn’t here, use the component routing table further down.

Where component-specific troubleshooting lives

Cross-cutting checks

Before opening an issue, verify:

• The SDK version matches a supported core version — see the Compatibility matrix.
• The API key is set in the environment (AA_API_KEY) — an unset credential is the most common cause of “agent registration failed”.
• The gateway URL is reachable from the host running the agent (AA_GATEWAY_URL, defaulting to http://localhost:7391, a local gateway auto-started via aasm start if none is already running).

Still stuck? Open an issue

If none of the routes above resolve the problem, open a GitHub issue on the owning repository — the core team monitors each repo’s issue tracker and routes docs bugs back here.

Last reviewed: 2026-07-17 — AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Check a published claim

This section routes a published sentence to the evidence behind it, and routes a vulnerability to the people who can act on it; it holds no evidence of its own, because a copy of evidence is not evidence.

Take a sentence to its evidence, in three steps

1. Find the claim term

A statement about what happened to an action is incomplete without its timing and its failure posture. ADR 0033 §6 defines the canonical vocabulary for this, and downstream material is required to pick one of its terms rather than an undifferentiated verb.

The eleven terms are:

Observed · Detected · Evaluated · Denied before execution · Redacted · Approval required · Degraded · Unmeasured · Experimental · Planned · Unsupported

Two of those words appear on this site on a different axis. Planned and Experimental above are §6 terms about an action. The 🗺️ Planned you may have seen in the sidebar beside a page title is a documentation-area label from the status map, about an area of this documentation. A page is 🗺️ Planned because its area is; an action is Planned in §6’s sense. Neither licenses a conclusion about the other, and when you are checking a sentence it is the §6 sense that applies.

What each one means, and which mechanism can legitimately reach it today, are defined in ADR 0033 §6. This page names the terms so you can find them; it does not define them, because a second definition is how two definitions start disagreeing.

If a sentence uses none of these terms, that is the finding.

2. Ask for the evidence that term requires

Each term in §6 carries the evidence that substantiates it, and they are not interchangeable: a durable event attributed to an action substantiates Observed, and does not substantiate Denied before execution, which needs a refusal by a component sitting before the effect.

Three signals look like coverage and are not, and ADR 0033 §7 names them so they cannot be offered as substantiation: an environment variable that replaces a probe result, a probe satisfied by a binary being present on $PATH, and a capability bit asserted unconditionally.

3. Check the completeness claim separately

A statement usually carries two claims at once: what happened to an action, and how much was covered. They have different owners and different evidence, so they are checked separately and the more restrictive published outcome governs.

Report a vulnerability

Do not report a security issue through a public GitHub issue.

Vulnerability reports go to the repository that owns the affected code, through GitHub’s private vulnerability reporting on that repository, and each repository’s SECURITY.md carries its current reporting route and disclosure policy:

The organisation-wide security policy is the fallback for any repository that does not publish its own, and the rows above were checked rather than assumed.

If you are unsure which repository owns the code, file against core so it can be routed.

The reporting address is deliberately not repeated on this page. Each SECURITY.md above is the canonical source for its own route, and a copied address is one that keeps working right up until it does not.

What this page does not do

• It does not hold evidence. It routes to the artifact that does.
• It does not define a claim term. ADR 0033 §6 does.
• It does not decide whether a statement may be published. For managed-service wording that is the SaaS claim publication checklist.

Going deeper

The claim vocabulary, the evidence each term requires, and the mechanisms mapped onto them are in ADR 0033.

Last updated: 2026-08-13 by AI Agent Assembly Team

SaaS claim publication checklist

This page is the control that keeps the managed-service claims off this hub until they are true. It exists for two audiences: readers who want to know why the SaaS pages are almost empty, and maintainers who are about to add a managed-service claim back.

⚠️ Provisional. This page was authored alongside the removals it records, ahead of the canonical claim-governance ADR (AAASM-5621) that will define the approval semantics, owner roles, and evidence grades this org actually uses. Where this page and that ADR disagree, the ADR wins and this page gets rewritten to match. It is expected to become an adoption record feeding the capability/evidence manifest (AAASM-5531) rather than a standalone registry. Treat the register below as an accurate record of what was removed and why — that part is evidence — and the approval workflow around it as a placeholder.

The rule it enforces is narrow and absolute in one direction only:

A managed-service operational or contractual claim may not be published on this hub until the service exists, a named owner has approved the claim, and the evidence listed below has been produced.

“Removed rather than softened” is deliberate. Rewording “99.9% uptime SLA” into “high availability” does not reduce the commitment a reader takes away from it; it only makes the commitment harder to audit. Unevidenced claims are deleted.

Scope

This checklist covers claims about the managed AI Agent Assembly service: its availability, plans, quotas, regions, onboarding, billing, support, and legal or compliance posture.

It does not cover the open-source stack. Apache-2.0 behaviour is documented normally, in core docs, the policy reference, the security model, and Docker & containers.

How to use it

1. Find the claim class you want to publish in the register below.
2. Produce the evidence in the Evidence required column. Link it from the pull request.
3. Get written approval from the role in the Approval owner column. An approval covers a specific wording, not a topic.
4. Publish the claim with the wording that was approved, and add the label the claim’s maturity warrants — see Source of truth & status for the label vocabulary this hub uses.
5. Update the register row so the next maintainer can see what was approved and on what basis.

If a claim is not in the register, it does not get a fast path — add a row for it first.

Register of removed claims

Removed by AAASM-5612 on 2026-08-06 from Managed SaaS onboarding (design preview), Managed control plane (design preview), Open core boundary, and Security model.

The security-model rows differ from the rest in one way worth noting: several of those claims were not merely unevidenced, they were contradicted by the Apache-2.0 source. Where that is the case the row says so, because the evidence needed to restore such a claim is a code change, not an approval.

Approval owners are roles, not individuals, so the register does not go stale when people change. “Evidence required” is the minimum; an owner may ask for more.

Availability and service commitments

Plans, quotas, and pricing

Regions and data residency

Onboarding and account operations

Billing

Identity, provisioning, and access control

Audit and security posture

Legal and compliance

Language rules that apply to every row

These apply even after an owner approves a claim.

• Do not use the present tense for a capability that is not running. “Supports X” and “is available in X” are present-tense claims.
• Label the maturity. Use the label vocabulary in Source of truth & status. An unlabelled statement reads as shipped.
• Do not use unqualified absolutes — “all”, “every”, “complete”, “comprehensive”, “universal”, “unlimited”, “immutable”, “cannot be bypassed”. If one is genuinely correct, name the boundary it holds within and the evidence for it, in the same sentence.
• Do not publish a number you have not measured. Latencies, durations, retention periods, and quotas are measurements, not illustrations.
• Do not soften instead of removing. If the evidence is missing, the claim comes out.
• Check the claim against the code, not against the neighbouring prose. Several claims removed here were restated across three or four pages, and two contradicted the Apache-2.0 source outright. A claim that agrees with another doc is not thereby verified.
• Ask whether the mechanism exists and whether a released binary can reach it. Distinct from “is it worded correctly”, “does it hold once enabled” and “is it on by default”. A capability present in the source but unreachable in a shipped build — a sink hardcoded off, a daemon excluded from the release artifacts, a per-session filename never given a session — reads to a reader as a feature they have. Several claims here passed every other check and failed this one.
• Understating is also inaccurate. The goal is a claim that matches the system, not the smallest claim available. During this pass one control was initially written as weaker than it is — the audit chain was described as unverifiable when an operator command to verify it ships today. Removing an unevidenced claim and erasing a real one are different acts; only the first is the safe default.
• Name the scope a control actually covers. A mechanism that protects one sink, one protocol, or one code path should say which. “The audit log is hash-chained” and “the JSONL audit files are hash-chained, the database mirror is not” have very different operational consequences.

Related documentation

• Source of truth & status — the canonical maturity label for every area of this hub
• Managed SaaS onboarding (design preview) — managed onboarding, planned
• Managed control plane (design preview) — the managed control plane, planned
• Open core boundary — the open-source / commercial split
• Security model — the security posture of the open-source enforcement path, including the audit log’s actual integrity properties

Last reviewed: 2026-08-06 · AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Policy Reference

The field-by-field policy reference is maintained in Core, generated from the same schema aa-gateway validates against: Core policy reference. This page is a summary and a router to it — it does not restate field types, defaults, or validation rules, so it cannot drift out of sync with the schema the way a second hand-written copy can.

What a policy document is

A policy is a YAML document that scopes what an agent may do — which domains it can reach, which tools it can call, how much it can spend, and more. The gateway evaluates it and returns an allow, deny, or rate-limit decision; whether that decision is enforced before the action runs depends on which path the request took — see Security model for the per-path posture.

Where each block is documented

Core also documents filesystem and syscalls blocks (Linux host-level scope) that this hub does not summarise separately — see filesystem and syscalls in the Core reference.

What this page does not cover

Field types, defaults, validation rules, and enumerated valid values live only in the Core reference above — restating them here is exactly the duplication that let this page fall out of sync with ADR 0033 §2/§4 on when a policy decision actually binds before execution. If you need a field’s type or default, follow the link.

Going deeper

For worked example policies (minimal budget-only, network allowlist, capability control, rate-limiting with approval, business-hours schedule, PII detection, and a full policy exercising every section), see Core’s example policies.

Related documentation

• Security model — IronClaw layers and policy engine position in the stack
• Managed control plane — design preview — planned, not available
• Managed SaaS onboarding — design preview — planned, not available

Last updated: 2026-09-07 by AI Agent Assembly Team

Capability & protection status

This page is generated, row for row, from governance/capability-manifest.yaml in the agent-assembly monorepo — ADR 0034’s layer T2, the strongest layer any page on this hub (T5) may draw from. It does not restate or interpret those rows in prose; it renders them, so nothing here can broaden what the manifest itself claims (ADR 0034 Decision 2).

Every row is shown, including rows carrying Unsupported or Unmeasured coverage and Not applicable or Not measured protection state — those are the manifest’s own answer for that capability, not an omission.

What the columns mean

• Coverage — behaviour on evidence, ADR 0033 §6’s closed eleven-term vocabulary (Observed, Detected, Evaluated, Denied before execution, Redacted, Approval required, Degraded, Unmeasured, Experimental, Planned, Unsupported). One action, one host, one time.
• Protection state — ADR 0030 §4.1’s integration ladder for one dev-tool integration on one host: whether agent-assembly is installed, integrated and enforcing there at all. Distinct from coverage — a row can be Integrated and still carry no coverage evidence; see the manifest’s own governance/README.md “Three axes, three owners” section.
• Released channels / Platform — where the artifact that delivers this row’s capability is actually obtained, and on which platform families. Never a promise about what happens once installed — that’s coverage and protection state.

These three are never mixed into one cell. A capability can be released everywhere, integrated nowhere, and denied-before-execution on the one platform it does run — each of those is a separate, independently true statement, and folding them together would make one of the three appear to certify the others.

Provenance

• Manifest version: 1.0.0
• Ticket: AAASM-5531
• Fix version: agent-assembly v0.0.1-rc.7
• Extract taken at commit: e2730ddaf422
• Evidence surveyed at: 299de38830b5 (2026-08-06)

The evidence surveyed at commit is not this page’s own commit — it is the point in agent-assembly’s history the manifest’s rows were last verified against. A row is only as current as that commit, regardless of when this page itself was last regenerated.

Capability table

Unknown capability references

A page elsewhere in this hub that cites a manifest row (a capability_ids entry in its own metadata block, per Page standards) is checked against this same manifest by docs/scripts/validate_capability_ids.py — a reference to an id that does not resolve to a row here fails CI rather than publishing silently.

This page is regenerated from the capability manifest, not hand-edited — see Page standards for the metadata block every hub page carries.

Last updated: 2026-08-20 by AI Agent Assembly Team

Glossary

Plain-language definitions of the terms and acronyms used across this documentation. It exists so a first-time or non-specialist reader can decode the security and architecture jargon without leaving the page they are on.

Product concepts

AI Agent Assembly (AAASM)

The product this hub documents: a governance layer that sits between your AI agents and the outside world and enforces policy, tracks cost, and intercepts unsafe actions before they run.

Governance layer

The one-line description of what AI Agent Assembly is — a control that evaluates and enforces what an agent is allowed to do, rather than only observing what it did after the fact.

Gateway (aa-gateway)

The central service that holds the agent registry, evaluates policy, and tracks per-team budgets. Every interception mechanism reports to it.

Agent

An autonomous or semi-autonomous program that calls tools, models, or network services on your behalf — the thing AI Agent Assembly governs.

Policy

A set of allow / deny / audit rules that decide whether an agent action is permitted. See the Policy reference.

Policy-as-code

Expressing those rules as versioned YAML/JSON documents that can be reviewed and deployed through normal Git workflows, instead of clicking through a UI.

Budget

A per-team cap on token or dollar spend. When exceeded, the gateway can deny further agent calls.

Interception mechanisms

SDK layer

In-process governance: the language SDK wraps your agent’s calls and asks the gateway for a decision. It is advisory — Evaluated, not Denied before execution — since whether a refusal actually holds depends on the calling shim honouring the answer. See Security model.

Sidecar proxy (aa-proxy)

A companion process that intercepts an agent’s outbound HTTPS traffic to enforce policy without changing the agent’s code.

eBPF sensor (aa-ebpf)

A kernel-level sensor (Linux only) that watches TLS libraries and process syscalls and reports what it sees. Observe-only: it returns no verdict, blocks nothing, and is consulted in no allow/deny decision, so it observes and detects rather than preventing. It is deployed on its own, not as a tier the other mechanisms fall back to.

Security & identity terms

eBPF (extended Berkeley Packet Filter)

A Linux kernel technology for safely running small sandboxed programs inside the kernel to observe or filter events, without modifying kernel source.

uprobe (user-space probe)

An eBPF hook attached to a function in a user-space library (for example, an SSL library) so the sensor can observe calls at that point.

Sidecar

A deployment pattern where a helper process runs alongside your application and handles a cross-cutting concern (here, traffic interception).

MitM (man-in-the-middle)

Sitting in the path of a connection to inspect or control it. The proxy performs authorized MitM of an agent’s HTTPS using a per-host certificate authority so it can apply egress policy.

mTLS (mutual TLS)

TLS where both the client and the server present certificates, so each side cryptographically verifies the other’s identity.

STRIDE

A threat-modeling framework categorizing risks as Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, and Elevation of privilege. Used in the Security model.

SCIM (System for Cross-domain Identity Management)

A standard protocol for automatically provisioning and de-provisioning users and groups from your identity provider into an application. 🗺️ Planned — not implemented in AI Agent Assembly. Listed here as a term you will meet in identity tooling, not as a capability that ships.

SSO / SAML 2.0 / OIDC

Single sign-on and the two federation protocols (SAML 2.0 and OpenID Connect) that let operators log in with an enterprise identity provider. 🗺️ Planned — not implemented in AI Agent Assembly. There is no SSO implementation in aa-api, aa-gateway, or aa-auth, and no console to sign in to; operators authenticate with an API key or a JWT. Do not plan an IdP integration against it — see Authentication flow.

Ed25519

A modern public-key signature algorithm. Used here for the one-time possession proof an agent presents at registration — a signature over a server-issued nonce. It is not a reusable bearer credential: subsequent calls carry a random credential token instead. See the Security model.

AES-256-GCM

A symmetric authenticated-encryption algorithm. 🗺️ AI Agent Assembly does not use it. This entry previously described it as encrypting stored secrets at rest; there is no AES-256-GCM implementation in the workspace crates, no HSM or KMS integration, and no managed secret vault. Do not treat this stack as a secret store — see Secrets management. The term is retained here only so a reader who met the old claim can find its correction.

HMAC-SHA256

A keyed hash. Used here for the REST/admin session JWT, and to verify inbound audit webhooks received from SaaS coding-agent providers — there is no outbound webhook signing path. It is not used on audit-log entries: there is no log-signing key anywhere in the codebase; see Audit log below.

IronClaw five-layer defense

The name for AI Agent Assembly’s defense-in-depth model — five security layers (Boundary, Identity, Policy, Vault, Telemetry). These are distinct from the interception mechanisms (SDK, proxy, eBPF), which each live inside the Boundary layer and are deployed independently of one another. The Vault layer is largely aspirational: an in-memory secrets store is mounted but is empty in every shipped build with nothing able to populate it, there is no encryption at rest or key management, and where resolution does succeed the plaintext is returned to the caller. See Secrets management.

Audit log

The record of policy decisions and agent-reported events, written to JSON Lines files, with database tables holding a queryable mirror. A shipped gateway writes one fixed gateway-default.jsonl, not per-session files. Four bounds matter and are easy to assume away: the JSONL files are chained with an unkeyed SHA-256 digest (verify with aasm audit verify-chain), so the chain detects casual edits but not an actor who can rewrite the file and re-chain it; the database mirror carries no chain metadata and cannot be verified; the log is append-only by convention, not by an enforced constraint; and emission is best-effort, so an entry can be dropped under backpressure and budget debits produce none at all. Absence of an entry is not proof that an action did not occur. See Audit log for the full statement.

Last updated: 2026-09-07 by AI Agent Assembly Team

Compatibility Matrix

AI Agent Assembly ships as several independently released programs — the core monorepo (gateway, policy engine, sensors, runtime client) and the Python, Node, and Go SDKs. Compatibility here means a cross-component contract: a core release and the SDK release that speaks its wire protocol. An SDK is compatible with a core release when it is built against — and serializes against — that core’s protocol contract (aa-proto).

The pairings below are usually 1:1 per release — each row maps one core release to the SDK release verified to speak its protocol — but a cell may also hold a version range (e.g. >=0.1.0,<0.2.0 or 0.1.x) when a core release is compatible with a band of SDK versions rather than one exact tag. Compatibility is not guaranteed across breaking changes: those are tracked through the Protocol column. A bump in a row’s protocol value (protocol/v1 → protocol/v2) marks a breaking boundary, and the affected rows carry a numbered footnote explaining the break and which SDK range is required. Long provenance and caveat text lives in the Notes footnote list below the table, so the table itself stays compact — each cell is just a version, a range, or —. Each Core release cell carries a small superscript footnote (e.g. v0.0.1-alpha.5²) hanging off the release identifier; clicking it jumps to that row’s provenance note at the bottom of the page.

Latest published versions

All four badges read the live latest published version, so they stay current without maintenance. Python reads PyPI and Node reads npm’s rc dist-tag. Core uses shields.io’s github/v/release endpoint (include_prereleases&sort=semver): the monorepo carries a non-release spec/* tag that pollutes plain github/v/tag semver sorting, and core cuts GitHub Releases, so the release endpoint is the authoritative dynamic source. Go uses github/v/tag (sort=semver) because go-sdk publishes version tags but no GitHub Releases. Each badge links to the relevant registry or release/tag list for the authoritative current version.

Core ↔ SDK matrix

A cell of — means an exact, authoritative core↔SDK pairing could not be determined from a published tag or a committed pin, so none is asserted. The superscript on each Core release cell links that row to its provenance footnote in the Notes list below.

Notes

Runtime requirements

How this is maintained

This page is manifest-driven. The source of truth is compatibility.toml at the repository root. The matrix and requirements tables above are rendered from it by docs/scripts/generate_compatibility.py; the content between the BEGIN GENERATED / END GENERATED markers is generated — do not hand-edit it. Edit the manifest and regenerate:

python3 docs/scripts/generate_compatibility.py

A CI step runs the same script with --check, so any drift between the manifest and this page fails the build. The manifest is updated at each coordinated release; every cell traces to a published tag, a registry release, or a committed git pin (recorded in the Notes footnotes and the manifest comments). SDK cells may be a single version or a range, and breaking changes are recorded by bumping a row’s protocol value and adding a footnote — see the manifest comments for the range and breaking-change conventions, including a commented example.

Last updated: 2026-07-17 by AI Agent Assembly Team

1. Latest published core tag and the current product line. Sixth release-candidate in the v0.0.1 series, cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk: all four repos carry a v0.0.1-rc.6 tag, PyPI publishes 0.0.1rc6, and npm publishes @agent-assembly/[email protected] under the rc dist-tag. Each SDK at this tag is built against the matching rc.6 core revision, so the tag<->tag pairing is authoritative. ↩

2. Published core tag. Fifth release-candidate in the v0.0.1 series, cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk: all four repos carry a v0.0.1-rc.5 tag, PyPI publishes 0.0.1rc5, and npm publishes @agent-assembly/[email protected] under the rc dist-tag. Each SDK at this tag is built against the matching rc.5 core revision, so the tag<->tag pairing is authoritative. ↩

3. Published core tag. Fourth release-candidate in the v0.0.1 series, cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk: all four repos carry a v0.0.1-rc.4 tag, PyPI publishes 0.0.1rc4, and npm publishes @agent-assembly/[email protected] under the rc dist-tag. A release-pipeline completeness cut with no wire-protocol change: it ships the previously-omitted aa-api-server binary and publishes the aa-gateway container image, adds a release-artifact completeness gate, builds every supported Python interpreter (cp312/cp313/cp314), bundles the Node native .node binding, and serves local-mode gRPC agent registration on loopback 127.0.0.1:50051. Each SDK at this tag is built against the matching rc.4 core revision, so the tag<->tag pairing is authoritative. ↩

4. Published core tag. Third release-candidate in the v0.0.1 series, cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk: all four repos carry a v0.0.1-rc.3 tag, PyPI publishes 0.0.1rc3, and npm publishes @agent-assembly/[email protected] under the rc dist-tag. Each SDK at this tag is built against the matching rc.3 core revision, so the tag<->tag pairing is authoritative. ↩

5. Published core tag. Second release-candidate in the v0.0.1 series, cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk: all four repos carry a v0.0.1-rc.2 tag, PyPI publishes 0.0.1rc2, and npm publishes @agent-assembly/[email protected] under the rc dist-tag. Each SDK at this tag is built against the matching rc.2 core revision, so the tag<->tag pairing is authoritative. ↩

6. Published core tag. First release-candidate in the v0.0.1 series, promoting the channel up from beta. Coordinated across all four repos: agent-assembly + python-sdk + node-sdk + go-sdk each carry a v0.0.1-rc.1 tag (PyPI 0.0.1rc1, npm @agent-assembly/[email protected] under the rc dist-tag). ↩

7. Published core tag. Cut as a coordinated release across all four repos: agent-assembly + python-sdk + node-sdk + go-sdk each carry a v0.0.1-beta.4 tag (PyPI 0.0.1b4, npm @agent-assembly/[email protected] under the beta dist-tag). ↩

8. Published core tag. Cut as a coordinated release across all four repos: agent-assembly + python-sdk + node-sdk + go-sdk each carry a v0.0.1-beta.3 tag (PyPI 0.0.1b3, npm @agent-assembly/[email protected] under the beta dist-tag). ↩

9. Published core tag. Cut as a coordinated release across agent-assembly + python-sdk + node-sdk + go-sdk (monorepo AAASM-3004): all four repos carry a v0.0.1-beta.2 tag, PyPI publishes 0.0.1b2, and npm publishes @agent-assembly/[email protected] under the beta dist-tag. Each SDK at this tag is built against the matching beta.2 core revision, so the tag<->tag pairing is authoritative. ↩

10. Published core tag. First beta-channel pre-release in the v0.0.1 series (monorepo AAASM-2951), promoting the channel up from alpha. Coordinated across all four repos: agent-assembly + python-sdk + node-sdk + go-sdk each carry a v0.0.1-beta.1 tag (PyPI 0.0.1b1, npm @agent-assembly/[email protected]). ↩

11. Published core tag (2026-06-12 to 2026-06-14), between v0.0.1-alpha.5 and the beta.1 coordinated release. No SDK repository published a matching tag at this point in the alpha line: python-sdk’s alpha tags stop at v0.0.1-alpha.3, node-sdk’s at v0.0.1-alpha.4, and go-sdk’s at v0.0.1-alpha.5. SDK cells left as — per the accuracy contract. ↩ ↩2 ↩3 ↩4

12. All three SDKs pin aa-core/aa-proto/aa-sdk-client at git SHA 9cf8a033 (PR #958, 2026-06-05; 587 commits ahead of v0.0.1-alpha.5). This was the authoritatively-verified core<->SDK pairing before the beta line was cut. It is not a published core tag. ↩

13. Latest published core tag. No SDK tag pins exactly this commit; current SDKs pin a later SHA (see the pinned-commit row). SDK cells left as — to avoid asserting an unverified tag<->tag pairing. ↩

14. Published core tag. No SDK tag authoritatively pins this exact commit. ↩

15. Published core tag. SDK tags carrying the same version string (python/node/go of the matching alpha) exist, but at their tag time the SDK FFI crates did not yet pin a resolvable aa-core rev, so an exact commit<->commit pairing is NOT verifiable. Left as — per the accuracy contract. ↩ ↩2 ↩3

Source of truth & status

This hub routes across many independently shipped programs and repositories. Not all of them are public, and not all of them are generally available yet. This page is the canonical status map: for every documented area it records which repository owns the content, whether that source is public or private/internal, and whether the area is shipping today, in release candidate, or still planned.

When a page elsewhere in this hub describes a capability, look here first to know how much weight to put on it.

Status labels

Every area below is tagged with one visibility label and one maturity label.

Visibility — where the source lives and who can read it:

Maturity — how much to trust the described behaviour:

This is a documentation-area maturity axis, not the only one. The Horonomy company site separately labels each product’s portfolio stage (available, beta, release_candidate, coming_soon), which ranges over a product in the company’s portfolio, not an area of this hub’s documentation. The two are deliberately distinct axes with distinct owners — this page owns the one above — and neither may be read as the other. See ADR 0034 hand-off 7 for the full account.

Area status map

The protocol specification stays in the agent-assembly monorepo by project policy. The reserved agent-assembly-spec repository is intentionally not used as the spec source.

Why some areas are private or planned

AI Agent Assembly is open core — limited-function self-host (Docker Compose), full-function SaaS. The enforcement path — every interception mechanism, the policy engine, the SDK shims, and the CLI — is open source and public. The commercial control plane (Cloud) and the enterprise operations features (Enterprise) are delivered as a managed SaaS and live in private repositories; their documentation here describes intended behaviour, not a browsable codebase. See the Open core boundary for the full split.

Last reviewed: 2026-07-11 — AI Agent Assembly Team

Last updated: 2026-09-07 by AI Agent Assembly Team

Page standards — progressive disclosure & mandatory metadata

This page is for anyone authoring or reviewing a page on this hub. It defines how deep a page goes, how it hands a reader deeper, and what metadata every page must carry so that a claim can be checked mechanically instead of by reading.

It exists because the same capability gets described at five different depths by five different authors, and the shallow descriptions are the ones that drift into being wrong. A reader who stops at the first paragraph should hold a correct picture, not a simplified one — those are different properties, and only the first is achievable by rule.

What governs this page

This page is downstream of four artifacts. It adds no claim to any of them, and it does not restate their definitions.

ADR 0034 is the governing document for the vocabulary question, and it is merged. It shipped as AAASM-5621’s deliverable, and this page is written against its hand-off 7 and forbidden-design list. This page was deliberately sequenced to land after it, so that its central ruling would never be published without a source; that ordering is now satisfied.

It is linked above in the blob/HEAD source form rather than to the rendered docs site, because the published page — docs.agent-assembly.com/core/latest/adr/0034-… — still returns 404 while the site republishes after the merge, verified with ADR 0033’s published URL returning 200 as a control in the same check. When the rendered page resolves, swap that cell to the published URL, which is the form content-ownership.md prefers for one rendered site linking another.

Ticket references are plain text, not links: the tracker is not publicly readable, so a link would only reach a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

What this page does not decide

• Precedence between the three axes when they appear to conflict, and waivers. ADR 0034 owns both. This page applies its ruling; it does not extend it.
• Cross-repository adoption records and conflict resolution. Also ADR 0034 (AAASM-5621).
• Documentation-area maturity. source-of-truth.md owns it, and this page reads it rather than restating it — see area ids.
• A capability identifier registry. AAASM-5531 has landed (governance/capability-manifest.yaml in agent-assembly), and AAASM-5600 now validates capability_ids against it wherever a page declares the field — see the field reference. It stays optional in schema version 1 rather than becoming required: rolling every hub page onto a populated capability_ids list is AAASM-5610’s adoption work, not this ticket’s, so requiring the field here would fail every existing page for a rollout this page does not own.

The four disclosure levels

The levels are a property of a reader’s need, not of a page’s length. Each level adds precision; none of them retracts what the level above said. A reader must be able to stop at any level and still be correct.

Product promise is the reference instance for the levels: it carries all four for one subject. Read it as the worked example; this page is the general contract.

It is not yet a reference instance for the metadata. product-promise.md carries no metadata block — it merged before this contract existed — so running a validator over it today produces a hard error for the missing block, and rule 13 additionally fires on protects, enforces and catches, which appear there in double quotes as examples of banned wording. Both results are correct behaviour, not validator bugs. Adding blocks to existing hub pages is AAASM-5610’s work; the only page carrying one today is this one. The rule 13 double-quote exemption was added precisely because that page quotes the verbs it warns against.

Level 4 is never abbreviated

Depth is not a defect. No rule on this page — and no validator built from it — may be cited to remove technical detail from a component’s documentation, an ADR, a threat model or a protocol reference. There is no maximum page length, no maximum section count, and no requirement that a deep page carry a shallow summary of itself.

Progressive disclosure is about adding shallow entry points, never about subtracting depth. A page that was thinned to “fit a level” has been damaged, not improved. If a summary would replace its source, link the source instead — that is content-ownership.md’s prohibition on a derivative reproducing its source at the same depth.

Which levels a page must carry

Required levels are a function of page_type. A page may carry more levels than required; it may never carry fewer. The one exception is level 4 on a product or guide page, which is forbidden rather than optional — those types reach level 4 by handing off, because a page that both summarises and exhausts a subject is the “derivative that reproduces its source at the same depth” content-ownership.md prohibits. Rule 15 encodes this.