agent-assembly

Governance-native runtime for AI agents — open-source core.

Install the CLI

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

This downloads and installs the aasm binary to ~/.local/bin. Requires a published release. The installer script lives at scripts/install-cli.sh. The alternate host https://tool.agent-assembly.dev serves the same script.

# Pin a specific version
AASM_VERSION=v0.0.1-rc.7 curl -sSf https://agent-assembly.com/install.sh | sh

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

The raw raw.githubusercontent.com/.../install-cli.sh URL also works if you prefer to fetch the script directly from GitHub.

The default install is CLI-only — it installs the aasm command and never starts a background service.

Install additional components

aasm is the CLI. The runtime, proxy, and eBPF mechanisms are separate components. Select them by passing options to the script via sh -s -- (not to curl):

# CLI + local runtime
curl -fsSL https://agent-assembly.com/install.sh | sh -s -- --components cli,runtime

# Full local profile (cli + runtime + proxy)
curl -fsSL https://agent-assembly.com/install.sh | sh -s -- --profile full

Installing runtime does not start it — start it yourself afterwards.

Review-first install

Prefer to read the script before running it:

curl -fsSL https://agent-assembly.com/install.sh -o install.sh
less install.sh
sh install.sh --components cli,runtime

Homebrew (macOS / Linux)

brew install ai-agent-assembly/tap/aasm

Or tap once, then install by short name (add components as separate formulae):

brew tap ai-agent-assembly/tap
brew install aasm            # CLI only
brew install aasm-runtime    # runtime (start with: brew services start aasm-runtime)

Installs the latest tagged aasm release from the Homebrew tap. See the tap README for the full component matrix (aasm-runtime, aasm-proxy, aasm-ebpf, aasm-bundle). During the v0.0.1 series the published releases are pre-releases — see Project Status.

Note

Deprecated command: brew install ai-agent-assembly/agent-assembly/aasm (repo homebrew-agent-assembly) still works via a GitHub redirect but is deprecated — use ai-agent-assembly/tap/aasm.

Uninstall

For curl installs, the default uninstall removes the tools and keeps your local data (config, policies, state, logs):

aasm uninstall                          # remove tools; preserve data
aasm uninstall --components cli,runtime # remove only these components

To also remove Agent Assembly-owned local data, opt in explicitly (prompts for confirmation; preview with --dry-run):

aasm uninstall --all --purge            # remove tools + config + state
aasm uninstall --all --purge --dry-run  # show what would be removed

If aasm is missing or broken, the installer provides the same uninstall engine as a fallback:

curl -fsSL https://agent-assembly.com/install.sh | sh -s -- --uninstall

Homebrew installs are detected and left untouched by the above — remove them with Homebrew instead:

brew uninstall aasm            # plus aasm-runtime / aasm-proxy if installed

Overview

agent-assembly brings governance to AI agents at scale. An action on a governed path — a tool call, a network request, a budget spend — is checked against your policy, by a central gateway or by the sidecar proxy's local egress rules, and the outcome is recorded in a hash-chained, tamper-evident audit trail that aasm audit verify-chain re-verifies offline. Where nothing inspected the payload, the honest state is unmeasured — the proxy's transparent-tunnel path records "forwarded, and nothing looked at it", never clean. One known defect qualifies that: the CONNECT-level event for the same connection is still written as an allow, which ADR 0033 §2 logs as a truthfulness bug awaiting a code fix.

Governance is assembled from independently-deployable mechanisms rather than a fixed pipeline, and each one holds a stated boundary — lowest-latency first:

• SDK shim (in-process) — the fastest path, but it needs SDK adoption, an explicit initializer call and a reachable runtime. In this repo it reaches Evaluated (advisory); denied before execution depends on the out-of-repo shim honouring the answer, and the SDK is not a security boundary (ADR 0002).
• Sidecar proxy (aa-proxy) — refuses or redacts outbound HTTPS before it leaves the machine, without changing the agent's own code. It must be installed, started, routed to (HTTPS_PROXY) and have its CA trusted, and llm_only defaults to true, so only the built-in LLM hosts are decrypted. Linux and macOS. On macOS no prebuilt binary exists on any channel — not the GitHub Release assets, not the Homebrew tap, not the install.sh component installer, not GHCR — so a source build of the aa-proxy crate from crates.io (cargo install aa-proxy) is the only route.
• eBPF (aa-ebpf*) — Linux only; there is no macOS or Windows host adapter. Its TLS, file and exec probes reach observed / detected and no further — a blocked path sets an alert bit and the syscall still proceeds. Its one program that terminates rather than observes, the syscall guard, reaches detected plus asynchronous process termination — explicitly not denied before execution. It is off by default, and the offending syscall runs once before the SIGKILL lands. Its loader daemon has no prebuilt binary on any channel either; a source build of the aa-ebpf crate from crates.io is the only route.

A mechanism that is not deployed is reported as absent — nothing underneath silently picks up what it would have done. See the Architecture overview for the full picture, or jump straight to the Quickstart.

Governing an AI dev tool

Agents you write are one audience; the AI dev tool you run — Claude Code, Codex, Copilot, Windsurf — is the other. Those are governed through the Developer Integration lifecycle: aasm integrations plan / install / verify / status / repair / remove wires the tool's own configuration and launch path through Agent Assembly, then reports an evidence-backed protection level rather than asserting one.

Start at the aasm integrations CLI reference or the onboarding walkthrough, and read Limitations and known bypasses for what is measured and what is not.

This command group is stripped from the crates.io publish only, so cargo install aa-cli (which installs the aasm binary — there is no crate named aasm on crates.io) does not have it. A source build, the GitHub Release tarballs, the curl installer and the Homebrew formula all carry it. Its runtime surface is off by default on every channel. See the CLI overview.

Ecosystem

agent-assembly is the open-source core of a larger governance platform. The table below maps each production repository to its role and entry point, so you can move from this repo to the SDKs, the install tap, or the canonical docs.

Repository	Role	Status
agent-assembly (this repo)	Core runtime — gateway, policy engine, eBPF / proxy / SDK interception
python-sdk	Python SDK (PyO3 native + pure-Python client)
node-sdk	TypeScript / Node.js SDK (napi-rs native + JS client)
go-sdk	Go SDK
homebrew-tap	Homebrew tap for the aasm CLI
docs	Canonical documentation site
agent-assembly-cloud	Hosted SaaS control plane
agent-assembly-enterprise	Enterprise extensions (delivered via SaaS)

The protocol specification is maintained inside this monorepo under proto/ and docs/src/protocol/ — there is no separate spec package.

Crate Map

The Cargo workspace declares 30 members in the top-level Cargo.toml. The table below lists the core architectural crates; storage drivers, dev-tool adapters, and test harnesses are omitted for brevity. Two additional eBPF-target crates live alongside but are intentionally outside the workspace because they compile for the bpfel-unknown-none target.

Workspace members (core)

Crate	Role
aa-core	Pure logic, no_std-compatible domain types and traits
aa-proto	Protobuf message types — single source of truth for the wire format
aa-runtime	Tokio async runtime wrapper and agent lifecycle
aa-ebpf	eBPF orchestrator (loads probes/programs via aya-build)
aa-ebpf-common	Shared types between user-space and eBPF programs
aa-proxy	Sidecar HTTPS interception proxy (MitM with per-host CA)
aa-sdk-client	Shared SDK runtime-client (UDS transport, codec, lifecycle) the language shims wrap
aa-wasm	WebAssembly target via wasm-bindgen
aa-gateway	Control plane — policy evaluation, agent registry, budget tracking
aa-api	HTTP presentation layer with OpenAPI spec generation (utoipa)
aa-cli	aasm command-line tool
conformance	Cross-SDK protocol conformance test harness

Out-of-workspace eBPF target crates

These two are built by aa-ebpf/build.rs (via aya-build) for the BPF target — they are not part of the host workspace and cannot be selected with cargo -p:

Crate	Role
aa-ebpf-probes	Userspace probe loaders (uprobes for SSL libraries)
aa-ebpf-programs	eBPF programs compiled to BPF bytecode (bpfel-unknown-none)

Project Status

🚧 Release candidate — v0.0.1-rc series (status as of 2026-09-08). The public API and wire protocol are not stable; do not use in production.

Releases are published as GitHub pre-releases — latest v0.0.1-rc.7 (2026-09-08). The coordinated release tag also publishes the CLI, crates, SDK packages, and container image:

Channel	Status
GitHub Releases	✅ Pre-releases published (v0.0.1-alpha.1 … alpha.9, v0.0.1-beta.1, beta.2, beta.4, v0.0.1-rc.1 … rc.6)
crates.io	✅ Workspace crates published at the pre-release version
Homebrew tap	✅ aasm formula published for tagged releases
PyPI / npm	✅ SDK pre-releases published from the release tag
GHCR image	✅ Published from the release tag

See docs/release/ for the per-tag release notes and the release runbook.

Requirements

• Rust stable (≥ 1.75)
• protoc — Protocol Buffers compiler (brew install protobuf on macOS, apt-get install protobuf-compiler on Debian/Ubuntu); required by aa-proto and aa-gateway build scripts
• cargo-nextest for running tests
• cargo-deny for dependency checks
• Lefthook for git hooks
• Linux only: pkg-config and libssl-dev (or openssl-devel on RHEL-family) for native TLS in aa-proxy; eBPF crates additionally require a recent kernel with BTF and a nightly Rust toolchain (see aa-ebpf/README.md)

Supported platforms

Reach differs per mechanism. The canonical, evidence-cited matrix is §5.3 of ADR 0033; this is a summary of it, and where the two disagree the ADR is right.

Platform	Runtime / CLI	Sidecar proxy (aa-proxy)	Host-level (eBPF)
Linux x86_64	Implemented	Implemented	Implemented — observation (TLS / file / exec); syscall guard opt-in and asynchronous. Needs kernel ≥ 5.8 with BTF and a nightly toolchain
Linux aarch64	Implemented	Implemented	Implemented (partial) — TLS and exec only; no file-I/O kprobes, whose attach targets are __x64_sys_*
macOS (Apple Silicon / Intel)	Implemented	Implemented, with conditions — no prebuilt binary on any channel, and CA trust is attempted at proxy start via an admin prompt that fails startup if refused	Unsupported — no host adapter exists
Windows	Unsupported	Unsupported	Unsupported

Windows is unsupported in all three columns rather than partial: aa-proxy uses tokio::signal::unix unconditionally so the crate has no Windows build path, aasm takes aa-proxy as an unconditional dependency, no release target is a Windows target, and no ETW, WFP or minifilter code exists. WSL2 is Linux — a Linux binary in a Linux VM is the Linux row, not Windows support, and reading it the other way is what ADR 0033 forbidden design 5 rules out.

Where a mechanism is unsupported it is absent, and absence is reported as absence: nothing underneath picks up what it would have done. See aa-ebpf/README.md for kernel requirements.

Quickstart

Demo recording: asciinema play docs/quickstart.cast

Prefer Codespaces? The .devcontainer/ config installs all dependencies automatically.

Get from a fresh clone to a verified local environment in under 10 minutes.

1. Clone the repository

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

2. Bootstrap the development environment

make dev-setup

Installs required toolchains, clones the SDK polyrepos as siblings, installs git hooks, and builds the workspace. Expected output (abbreviated):

  Cloning python-sdk ...
  Cloning node-sdk ...
  Cloning go-sdk ...
pre-commit installed at .git/hooks/pre-commit
   Compiling aa-core v0.0.1 ...
    Finished `dev` profile target(s) in 167s

dev-setup complete. Run 'make dev-verify' to validate.

3. Verify the installation

make dev-verify

Runs smoke tests across all SDK repos in parallel then checks gateway health. Expected output:

dev-verify: running SDK smoke tests in parallel ...
[1/4] python smoke ... OK (2s)
[2/4] node smoke   ... OK (18s)
[3/4] go smoke     ... SKIP (internal/smoke/ not found in go-sdk)
[4/4] gateway health ... OK (1s)

dev-verify passed (22s total)

Timing: ~4 minutes on a 2024 MacBook Pro M3 (first run; subsequent runs skip already-installed tools).

Next steps

• SDK repositories — Python, Node.js, and Go SDK guides
• Architecture Overview — three enforcement mechanisms
• Policy examples — reference governance policies
• Runnable examples — learn the runtime, CLI, and policy behavior by running small, framework-specific examples for Python, Node.js/TypeScript, Go, policy enforcement, approvals, audit, trace, and runtime workflows

Running with Docker Compose

Run aa-runtime as a sidecar against a placeholder agent using the examples/docker-compose stack:

# 1. Build the workspace (first time only)
cargo build --workspace --exclude aa-ebpf

# 2. Launch the sidecar + a stub agent container
cd examples/docker-compose
AA_API_KEY=dev-local-key docker compose up

The sidecar exposes:

• The agent IPC socket at /tmp/aa-runtime-my-agent-001.sock
• Readiness probe at http://localhost:8080/ready

To run only the governance gateway (without Docker), point it at one of the bundled YAML policies:

# Listens on 127.0.0.1:50051 by default; SDK shims and aa-proxy connect over gRPC.
cargo run -p aa-gateway -- --policy policy-examples/low-risk.yaml

policy-examples/{low,medium,high}-risk.yaml are reference policies — pick one or write your own following the same schema.

Replace the agent-stub service in examples/docker-compose/docker-compose.yml with your own SDK-based agent image once python-sdk, node-sdk, or go-sdk is wired into your project.

Repository Layout

agent-assembly/
├── aa-core/             # Domain types (no_std)
├── aa-proto/            # Protobuf message types (wire format)
├── aa-runtime/          # Async runtime + agent lifecycle
├── aa-ebpf/             # eBPF orchestrator (workspace member)
├── aa-ebpf-common/      # Shared user/kernel types (workspace member)
├── aa-ebpf-probes/      # Userspace probe loaders (out-of-workspace, BPF target)
├── aa-ebpf-programs/    # eBPF programs (out-of-workspace, BPF target)
├── aa-proxy/            # Sidecar HTTPS proxy
├── aa-sdk-client/       # Shared SDK runtime-client (Python/Node/Go shims live in their own repos)
├── aa-wasm/             # WASM target
├── aa-gateway/          # Control plane (policy, registry, budget)
├── aa-api/              # HTTP API + OpenAPI
├── aa-cli/              # CLI tool (aasm)
├── conformance/         # Protocol conformance test harness
├── proto/               # Protobuf source (.proto files)
├── openapi/             # Generated OpenAPI v1 spec
├── schemas/             # JSON schemas (compatibility matrix)
├── dashboard/           # Community web UI (React + TypeScript)
├── docs/                # mdBook contributor documentation
└── policy-examples/     # Reference governance policies

Documentation

📖 Canonical docs site: https://docs.agent-assembly.com/

The contributor-facing documentation is also published as an mdBook. Sources live under docs/src/. Build it locally with:

cargo install --locked --version 0.5.2 mdbook
cargo install --locked --version 0.17.0 mdbook-mermaid
mdbook serve docs --open

Chapter	Description
Introduction	Book overview and audience
Architecture Overview	Crate dependency graph, three enforcement mechanisms, IPC, sidecar lifecycle, policy evaluation
API Reference	rustdoc generation flow and per-crate API surface map
Command-Line Interface	aasm global flags, command groups, and examples
Policy YAML Reference	Per-section policy field reference, requires_approval_if expression syntax, and example policies
Dashboard	Web console and terminal (TUI) governance dashboards
Local Development	From-clone setup, everyday build/test loop, git hooks
Releases	Release state, distribution channels, and process
Compatibility Matrix	Which aa-runtime versions work with which SDK versions
Versioning Policy	Protocol semver rules, breaking-change classification, deprecation lifecycle
Protocol Changelog	Wire-protocol change log
Migration Template	Guidance for moving between protocol versions
Benchmarks — Baseline	Performance baseline numbers
Benchmarks — Policy Check p99	Latency SLA evidence

Security & Support

• Security: Report vulnerabilities privately via GitHub Security Advisories or email security@agent-assembly.com. Please do not open public issues for security reports. See SECURITY.md for the disclosure policy and response SLA.
• Bugs & features: Open an issue using the bug report or feature request template.
• Contributing: See CONTRIBUTING.md for the development setup, commit conventions, and PR process.
• Changelog: CHANGELOG.md.

License

Licensed under the Apache License, Version 2.0.