Requirements
Before you install Agent Assembly, make sure your machine meets the prerequisites below. The CLI and the governing gateway run on macOS and Linux; only the kernel-level eBPF mechanism is Linux-only.
At a glance
| You want to… | You need |
|---|---|
Install and run the aasm CLI from a release | A supported OS (macOS or Linux) — nothing else |
| Build the workspace from source | Rust stable ≥ 1.75, protoc, and a C toolchain |
| Run the SDK or sidecar-proxy mechanisms | macOS or Linux |
| Run the eBPF mechanism | Linux only — a recent kernel with BTF and a nightly Rust toolchain |
Supported platforms
The three enforcement mechanisms have different platform reach. The SDK shim
and the sidecar proxy (aa-proxy) run anywhere the runtime builds; the
kernel-level eBPF mechanism is Linux-only.
| Platform | Runtime / CLI | Sidecar proxy (aa-proxy) | eBPF |
|---|---|---|---|
| Linux (x86_64 / arm64) | ✅ | ✅ | ✅ — kernel with BTF + nightly toolchain |
| macOS (Apple Silicon / Intel) | ✅ | ✅ | ❌ — Linux-only |
| Windows | ⚠️ via WSL2 | ⚠️ via WSL2 | ⚠️ via WSL2 |
On macOS, governance runs through the SDK and proxy mechanisms; eBPF
is unavailable. See aa-ebpf/README.md
for kernel requirements.
Installing the CLI only
If you just want the aasm operator CLI from a published release, you need
nothing more than a supported OS. The quick-install script
downloads a pre-built binary for x86_64/aarch64 on macOS
(apple-darwin) and Linux (unknown-linux-gnu). Jump straight to
Installation.
Linux runtime requirement
The prebuilt Linux release binaries (x86_64 and aarch64) require glibc ≥ 2.28
(Debian 10+, Ubuntu 20.04+, RHEL / AlmaLinux / Rocky 8+). They are glibc-linked,
not musl, so Alpine is not a supported host for them. The release workflow builds
them in a pinned glibc 2.28 container and fails if any shipped executable requires
a newer GLIBC_x.y symbol (scripts/release/check_linux_glibc_baseline.py; the
baseline value is scripts/release/linux-glibc-baseline.txt).
Building from source
To build the Cargo workspace yourself — for development, or to run the gateway
via cargo run — install the following.
Required
- Rust stable, ≥ 1.75 — install via rustup. The workspace uses the 2021 edition.
protoc— the Protocol Buffers compiler, required by theaa-protoandaa-gatewaybuild scripts.- macOS:
brew install protobuf - Debian / Ubuntu:
apt-get install protobuf-compiler
- macOS:
Recommended developer tooling
These are not needed to run the CLI but are used by the test and contribution workflow:
cargo-nextest— the test runner used across the workspace.cargo-deny— dependency and license checks.- Lefthook — git pre-commit / pre-push hooks.
Linux-only build dependencies
On Linux, the native-TLS path in aa-proxy additionally requires:
pkg-configlibssl-dev(Debian/Ubuntu) oropenssl-devel(RHEL-family)
Requirements per enforcement mechanism
Each mechanism can be deployed independently. Pick the mechanisms you need and install only their requirements.
| Mechanism | What it does | Requirements |
|---|---|---|
| SDK shim (in-process) | Fastest path; the agent adopts a language SDK that reports to the gateway | The relevant SDK: python-sdk, node-sdk, or go-sdk. Runs on macOS or Linux. |
Sidecar proxy (aa-proxy) | Intercepts routed outbound HTTP/1.1 via MitM, using per-host certificates minted from a local root CA. No agent code change, but the process must honour HTTP_PROXY/HTTPS_PROXY and trust the CA | macOS or Linux; Windows unsupported. On Linux, pkg-config + libssl-dev/openssl-devel, and CA trust is an explicit sudo aasm proxy install-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. |
| eBPF (kernel) | Observes OpenSSL TLS plaintext plus exec/file syscalls — reports, does not block. TLS uprobes and exec tracepoints work on x86_64 and aarch64; the file-I/O kprobes are x86_64-only (hardcoded __x64_sys_*) | Linux only. A recent kernel with BTF enabled and a nightly Rust toolchain to build the BPF-target crates. Not available on macOS. |
The eBPF caveat. The
aa-ebpf-probesandaa-ebpf-programscrates compile for thebpfel-unknown-nonetarget and are intentionally outside the host Cargo workspace. They cannot be selected withcargo -pand do not build on macOS. If you are on macOS, you can still run and govern agents through the SDK and proxy mechanisms — you simply do not get the kernel-level mechanism.
Execution isolation (aasm run --isolation)
This is a separate capability from the three enforcement mechanisms above, with its own, narrower platform reach.
| Platform | aasm run --isolation process/auto | Requirement |
|---|---|---|
| Linux | ✅ | Either a separately-installed Sandlock executable on PATH (or AA_SANDLOCK_BIN), or the AASM-native backend (Linux 6.2+ with Landlock ABI v3 and the aa-isolation-launch binary; syscall filtering is x86_64-only) |
| macOS (Apple Silicon) | ⚠️ Experimental (proof-of-concept substrate, not shipped in any release; operator-built guest kernel/rootfs; no CI lane) — works with --isolation process --isolation-backend aasm-macos-vm (--isolation auto considers it last) | AA_ISOLATION_MACOS_VM_{HELPER,KERNEL,ROOTFS} (built from aa-isolation-macos-vm-poc/README.md) + com.apple.security.virtualization entitlement; filesystem-only confinement, hardware-qualified for Apple Silicon (see the support matrix linked below) |
| macOS (Intel) | ❌ Refused, never silently unconfined | Not supported — guest kernel/helper are arm64-only |
| Windows | ❌ Refused, never silently unconfined | No backend targets Windows |
See Execution isolation for the full support matrix, the runtime prerequisites, and what to expect when the backend is absent.
Next
With the prerequisites in place, continue to Installation.
Last updated: 2026-11-06 by Chisanan232