aegis-sandbox

Aegis

Claude Code's sandbox lets an agent read your SSH keys and AWS credentials by default. Aegis doesn't.

Two layers, both verified on real hardware.

Kernel sandbox — the agent's own shell cannot reach a denied path:

$ ! cat ~/.ssh/id_rsa
cat: /Users/you/.ssh/id_rsa: Operation not permitted

$ ! cat ~/.aws/credentials
cat: /Users/you/.aws/credentials: Operation not permitted

$ tail ~/Library/Application\ Support/Aegis/denials.log
kernel denied file-read-data /Users/you/.ssh/id_rsa to cat(pid 41560)
kernel denied file-read-data /Users/you/.aws/credentials to cat(pid 42180)

MCP proxy — same tool, same file, with and without Aegis in front:

direct to the server:   allowed: TOKEN=proof-env-secret
through aegis proxy:    AEGIS DENIED: read_text_file
                        Reason: path matches deny rule '.env'
                        Rule: deny_paths

What it does

Sits between your AI coding agent and your machine:

• Deny by default on every tool call
• Kernel sandbox on subprocesses — cat .env can't bypass it
• Tamper-evident audit log — hash-chained, integrity checked by aegis doctor, and checkpointed from outside the sandbox under a key the sandbox can't read or write
• Outbound requests checked before they're made
• Secrets never reach the MCP server

Install (macOS Apple Silicon)

New here? docs/getting-started.md is the step-by-step path, including the two questions that default to No.

Followed earlier instructions that said aegis-mcp? That package is not Aegis — it is an unrelated project installed under the same import name, aegis. Remove it first:

python3 -m pip uninstall aegis-mcp

If aegis-sandbox is already installed, that uninstall also deletes two of its files, so reinstall it afterwards: python3 -m pip install --force-reinstall aegis-sandbox.

python3 -m pip install aegis-sandbox
aegis init      # detects Claude Code / Cursor, asks a few questions
aegis doctor    # proves the boundary is actually in place

Upgrading? Re-run aegis init. Your policy.json is yours and is never rewritten behind your back, so a new sandbox domain does not appear on its own — and without the OAuth token endpoint a sandboxed client stops working when its token expires. aegis init offers the new hosts; accepting is one keystroke.

Prefer an app? Download the .dmg

SHA256: bcccaa957fd3a0a15413eb1207a012f0328e309d078e7b7f2af853915e64c6dc

Unsigned build — right-click the app → Open the first time (macOS will warn about an unidentified developer, that's expected). Or build from source.

What it does NOT do

• Does not stop prompt injection
• Kernel escape defeats the sandbox
• The audit database is still writable from inside the sandbox. Checkpoints make tampering with already-checkpointed history detectable — not impossible, and the newest rows aren't covered yet
• A sandboxed client can't log in at all. Log in to Claude Code before aegis init; aegis doctor fails if a wrapped client isn't logged in
• A sandboxed client can't renew an expired login token — run it once outside the sandbox to refresh
• The sandbox can still read your OAuth token from the Keychain
• Tool results larger than 16 MiB are refused
• No external security review, no certifications
• Not audited by anyone but me — read the source, that's why it's MIT

Full threat model: THREAT-MODEL.md

License

MIT