Unify the stack you have—or test its strongest boundary.

Install the binary

The installer downloads the release tarball for your platform and verifies it against the checksums.txt published with the release before installing. One static binary, no runtime dependencies.

curl -fsSL https://raw.githubusercontent.com/Tarekkharsa/agentstack/main/install.sh | sh

Prefer to build it yourself? From a checkout: cargo build --release, then ./target/release/agentstack self link to symlink it onto your PATH. Release binaries are built with sandbox support compiled in, so run --sandbox works out of the box; a bare cargo build omits it unless you pass --features sandbox.

You should see

$ agentstack --version
agentstack 0.10.x

Register the gateway, once

One registration teaches every installed agent CLI to reach its MCP servers through agentstack instead of directly. No files are copied into any repo — the gateway serves each project live, behind the trust gate you're about to meet. connect without --write is a dry run that shows the exact config diff first.

agentstack connect --all            # dry run: shows what would change
agentstack connect --all --write    # write it into each harness's global MCP config

Undo any time with agentstack disconnect; verify with agentstack doctor.

Clone a repo — and watch it stay inert

Grab any repo that ships its own agent setup. (No repo in mind? The runnable docs/trust-gate-demo.sh builds a tiny one for you.) Before you've reviewed it, ask an agent what it can use here — the answer is nothing. No MCP server is spawned or contacted, no secret is resolved, no skill enters context. That inert-until-trusted invariant is property-tested in the trust crate.

You should see

$ git clone https://github.com/some/agent-repo && cd agent-repo
$ agentstack mcp --auto-project     # an agent asks: which project servers can I use?
  ✗ untrusted — no servers spawned, no secrets resolved, nothing in context

Review what it declares, then trust it

trust shows you exactly what the repo declares — the servers it would spawn and the commands behind them — before you authorize anything. Trust pins a content digest of the manifest, local overlay, and lockfile, not the arbitrary code they point at, so read any referenced script as part of the review (the same discipline as reading a .envrc before direnv allow). Any later edit to the manifest or lock re-gates the repo — new pins mean fresh consent.

agentstack trust .

You should see

$ agentstack trust .
  ▶ demo: runs `python3 ./server.py`   # exactly what it would run
  ✓ trusted at sha256:945b4b…             # editing the manifest re-gates it

Now the same agentstack mcp --auto-project serves the repo's servers live — and every brokered call passes two firewall layers (the repo's [policy.tools] and your machine-level rules, which no repo can loosen) and lands in ~/.agentstack/audit/calls.jsonl.

Store any secret it needs — in your keychain

If the repo references a token (as a ${REF}), store it once. It goes into your OS keychain, never into the manifest or any committed file. Resolution is fail-closed: if a referenced secret can't resolve, the write or run is blocked rather than emitting a placeholder into live config.

agentstack bootstrap            # names any missing secret
agentstack secret set GH_PAT    # store it in the OS keychain

agentstack doctor confirms every server, skill, and secret is wired up, and names the exact fix for anything that isn't.

Run it confined — needs Docker

The trust gate decides what the agent may do. run --sandbox decides what it can do: the harness runs in a container whose egress is filtered by your machine [policy.egress], and --lockdown goes further — the container's only network peer is the egress-proxy sidecar, so an agent that ignores the proxy reaches nothing. Preview the exact enforcement plan and posture first with --plan, then launch.

agentstack run claude-code --sandbox --lockdown --plan   # preview posture + enforcement
agentstack run claude-code --sandbox --lockdown          # launch confined

You should see

$ agentstack run claude-code --sandbox --lockdown
  ▲ LOCKDOWN / ENFORCED · NO DIRECT ROUTE   # the posture, once, up front
  container on an internal-only network → sole peer is the egress proxy
  ✓ api.anthropic.com:443   allowed by [policy.egress] — recorded
  ✗ evil.example.com:443    denied — no such host in policy — recorded

Runnable end to end (needs Docker): agentstack-test/demo-lockdown.sh.

Honest scope: hosts you allow stay reachable. agentstack restricts destinations and records every decision — it does not inspect payloads, so it can't guarantee sensitive content never leaves through a host you approved. The claim is unapproved egress is blocked, never "exfiltration is impossible."

Read the flight recorder

Nothing trusted runs unobserved. A sandbox run fails closed if its run log can't be created; that log captures the container lifecycle, egress decisions, brokered tool calls, and secret-reference names, tagged with the run's posture. It never stores argument values or secret values. agentstack report <run-id> reads it back.

agentstack report <run-id>        # that run's decisions
agentstack report <run-id> --json # machine-readable, carries the posture slug

You should see

$ agentstack report r-0859dcee73
  run 2026-07-11T…  posture: LOCKDOWN / ENFORCED · NO DIRECT ROUTE
  ├─ SandboxStarted   image=…  network=internal-only
  ├─ egress ✓ api.anthropic.com:443   allowed
  ├─ egress ✗ evil.example.com:443    denied
  └─ SandboxExited    code=0

Ran in host or gateway mode instead of a container? There's no flight recorder, but every brokered tool call is still in the call audit log — ~/.agentstack/audit/calls.jsonl, one line per call (tool · outcome · latency), storing an argument digest only, never raw values or resolved secrets. Trust-store mutations and per-run token/cost accounting are not yet wired into the flight recorder; see the enforcement matrix for exactly what each mode records today.