adarsh14734/aegis-releasesSandbox and MCP proxy that blocks AI coding agents from reading SSH keys, AWS credentials, and .env files, with deny-by-default policy and tamper-evident audit logs.
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
Each line is backed by a test that ran against this release; where something is not yet tested, it says so.
aegis workspace add / remove / list — change which folders the agent may work in without editing policy.json. Adding always needs --confirm-grant; removing never does. add refuses your home directory, anything containing Aegis's own files, a path with .., a folder that does not exist, a symlink sitting inside a workspace, and a workspace inside or around another one. Every change is recorded in the audit log and regenerates the sandbox profile. A session that is already running keeps the workspaces it started with — including one you just removed — measured against a live sandboxed session.aegis policy set-folder, granting wherever the link pointed; and a workspace created inside another could later be swapped for a symlink and followed at the next launch. Both were reproduced on 0.8.1 and are now permanent regression tests proven to fail there.policy.json are refused. A relative path resolved against the folder Aegis was started from, so aegis run and the launch wrapper could enforce different sandboxes from one policy (measured: different profile digests). Paths must be absolute or start with ~/.aegis doctor no longer reports a mismatch between an edit and the next launch.aegis run and aegis doctor print the real Claude Code path — read from the wrapper Aegis wrote — and /login, to run outside the sandbox. Not fixed: a revoked or expired token still reads as logged in until the first message fails (Claude Code's status reports no expiry), and login still cannot happen inside the sandbox; that needs a credential broker that does not exist yet.aegis init protects a new user who has not logged in yet. Found by following the walkthrough in a clean environment: in 0.8.1, a Claude Code that had never logged in was left unwrapped by default, behind a question the docs never mentioned, so claude stayed outside the sandbox. Now, once you say yes to sandboxing, it is wrapped, with a loud warning to log in once outside the sandbox (the real Claude Code path, then /login); aegis init's closing steps put that first, and aegis doctor fails until you do. The same run also fixed init's opening and closing text, gave aegis init, aegis run and aegis doctor one login instruction, and stopped a no-op change printing nothing to change (nothing to change).Not yet tested in 0.9.0: Linux; clients other than Claude Code; the /login flow end to end; a rebuilt desktop app.
Sits between your AI coding agent and your machine:
cat .env can't bypass itaegis doctor, and checkpointed
from outside the sandbox under a key the sandbox can't read or writeNew 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.
aegis init; aegis doctor fails if a wrapped client isn't logged inFull threat model: THREAT-MODEL.md
MIT