Opinionated out-of-the-box sandbox for claude and codex, with delicately crafted presets that already configure daily dev tools for you (common gotchas included). So you don't need to write cumbersome sandbox configurations in Claude Code or Codex settings, or to figure out which hosts pip, npm, and gh need, which paths to open, and what the agent must never write.
Claude Code's sandbox covers shell commands only, and Codex's network proxy skips MCP servers, so if you want the whole agent isolated, use Blackwall. It runs everything inside Anthropic's sandbox-runtime (srt), hooks and MCP servers included.
This project is named after the Blackwall in Cyberpunk 2077, a firewall NetWatch built to keep rogue AIs out of the Net.
Needs Node.js 22.21 or later.
npm install -g blackwall-sandboxLinux
sudo apt-get install -y bubblewrap socat ripgrep
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 # Ubuntu 24.04+ onlyShell completion
With oh-my-zsh:
mkdir -p $ZSH_CUSTOM/completions
blackwall --completion zsh > $ZSH_CUSTOM/completions/_blackwall # run it again after upgrading blackwallBlackwall or: How I Learned to Stop Worrying and Love the YOLO Mode:
# Claude Code can TRULY only read/write the current working folder (plus some other required paths defined in presets)
# Even with full Internet access granted, the blast radius is under control
blackwall --allow-internet claude --dangerously-skip-permissionsComparison: blackwall vs claude/codex built-in sandboxes vs srt
| Blackwall | Claude Code's built-in sandbox | |
|---|---|---|
| Covers | The whole agent and every process it starts, MCP servers included | Shell commands only. Read, Edit, Write, and WebFetch run outside it and follow permission rules. Hooks, MCP servers, and apiKeyHelper run with your full access |
| Reads | Denied everywhere, except the folders it writes, system paths, and what presets need | Most of your machine by default, ~/.ssh and ~/.aws/credentials included |
| Hosts | Only what presets and claude need, or every public host with --allow-internet, whatever the permission mode |
Your allowed domains, but in bypassPermissions mode a host you never allowed connects without a prompt, unless you set strictAllowlist or allowManagedDomainsOnly |
| Localhost and LAN | Private ranges denied by the private-network preset, and local-network keeps localhost denied under "*" |
Loopback denied, but an allowed name that resolves into your LAN, like 10.0.0.0/8, connects |
| Way out | No built-in escape hatch; known limitations still apply | Claude can retry a blocked command unsandboxed, unless you set allowUnsandboxedCommands to false. excludedCommands run unsandboxed either way |
| Blackwall | Codex's built-in sandbox | |
|---|---|---|
| Covers | The whole agent and every process it starts, MCP servers included | MCP servers, web search, and connectors run outside it |
| Reads | Denied everywhere, except the folders it writes, system paths, and what presets need | Everything, unless you write a permission profile |
| Hosts | Only what presets and codex need, or every public host with --allow-internet |
Off by default. Once on, every host is reachable, unless you also enable features.network_proxy and list your domains |
.git |
Writable, except hooks and config |
Read-only, so git commit needs an approval |
Blackwall is srt underneath, with the setup done for you:
| Blackwall | srt directly | |
|---|---|---|
| Reads | Denied everywhere, except the folders it writes, system paths, and what presets need | Everything by default, ~/.ssh included |
| Hosts | Only what presets and claude or codex need |
None, until you list each one in ~/.srt-settings.json |
| Every public host | --allow-internet for one run, or "*" in network.allowedHosts |
"*" is rejected |
| Localhost and LAN | Private ranges denied by the private-network preset, and local-network keeps localhost denied under "*" |
Loopback denied, but an allowed name can still resolve into your LAN |
~/.claude |
~/.claude-blackwall, with your CLAUDE.md, rules, skills, agents, commands, and output styles copied in on every launch |
Must be writable for claude to run, so the agent can edit your hooks and settings |
| Agent files in the repo | Also .claude/settings.json, .claude/settings.local.json, and .claude/hooks, and all six in --add-dir folders too |
.mcp.json, .claude/commands, and .claude/agents denied, beneath the current folder only |
| Tool setup | Presets for python, node, github, git, and pre-commit |
Yours to write: each tool's hosts, read paths, and cache folders |
| Project config | .blackwall/config.json, loaded only after --trust |
None, only --settings with a path |
| Inspection | --print-config, --print-file-access, --print-network-access, and --print-env |
--debug logs |
srt's security limitations apply to blackwall too.
blackwall claude # run Claude Code in the sandbox
blackwall --add-dir ../another-repo claude # also let it write to another folder
blackwall --allow-internet claude # also let it reach every public host, but not localhost or private ranges
blackwall npm test # any command works, not only claude
blackwall --print-config claude # show the merged config
blackwall --print-file-access claude # show what it can read and write, as srt sees it
blackwall --print-network-access claude # show which hosts it can reach, as srt sees it
blackwall --print-env claude # show the env vars blackwall adds, and why
blackwall --trust # trust .blackwall/config.json in the current folder
blackwall --version # show the blackwall version
blackwall --completion zsh # print the zsh completion script
blackwall --help # show the usageBy default, a sandboxed command:
- Writes only to the current folder,
--add-dirfolders,/tmp/claude,~/.cache-blackwall, and the Claude Code or Codex config folder - Never writes
.git/configor.git/hooks, in the current or--add-dirfolders.git remote add,git config, andgit branch -mfail;git push -u,git branch -D, andgit switch -close their tracking update. Set remotes and upstreams on the host, or push withgit push origin HEAD - Never writes the agent files the
agent-filespreset lists, in the current or--add-dirfolders. A sandboxedclaudecan't save project permission rules either - Reads only those folders, plus the
allowReadpaths in the default config and presets, and what Claude Code or Codex needs - Connects only to the hosts in presets, and the ones Claude Code or Codex needs
blackwall claude uses ~/.claude-blackwall as its config folder instead of ~/.claude. A sandboxed run never writes to ~/.claude, and reads only ~/.claude/plugins.
- Every launch copies your
CLAUDE.md,rules,skills,agents,commands, andoutput-stylesfrom~/.claude, so edits to the copies don't last - Plugins load read-only from
~/.claude/plugins, without auto-update - Sessions, settings, and login stay separate
settings.jsonstarts with only yourenabledPlugins, since hooks and permissions assume no sandbox. After that it's yours to edit
Log in with /login, or run claude setup-token outside the sandbox and put CLAUDE_CODE_OAUTH_TOKEN in ~/.blackwall/.env. The token is better: /login inside the sandbox stores a .credentials.json the agent can read, while the env var never reaches its shell.
blackwall codex uses ~/.codex-blackwall as its config folder instead of ~/.codex. A sandboxed run never writes to ~/.codex, and reads only ~/.codex/packages.
- Every launch copies your
AGENTS.mdandagentsfrom~/.codex, plusskillsfrom~/.agents, so edits to the copies don't last - Sessions,
config.toml,rules, and login stay separate. Put sandbox-specific rules in~/.codex-blackwall/rules/ - Codex's own sandbox is off (
-c sandbox_mode="danger-full-access"), since it can't start inside blackwall's. blackwall is the sandbox
Log in with blackwall codex login --device-auth.
skills/blackwall teaches Claude Code and Codex to run, configure, and debug blackwall. Inside the sandbox, the agent can't run blackwall or edit its config, so the skill tells it how to read a denial and what to hand you.
blackwall claude and blackwall codex copy it into their config folders on every launch, so it always matches your blackwall. For agents you run outside the sandbox:
npx skills add vinta/blackwall -gPut your env vars in ~/.blackwall/.env:
GH_TOKEN=xxx # generate a read-only PAT from https://github.com/settings/personal-access-tokensSandboxed commands get BLACKWALL_SANDBOX=1, so a script can tell it runs inside blackwall.
src/config/default-config.json holds the default settings. Only keys in default-config.json can be set in your ~/.blackwall/config.json or .blackwall/config.json, at the top level or, except srt, under overrideDefaults.
presets: ["agent-files", "python", "node", "github", "git", "pre-commit", "local-network", "private-network"]: The presets on by defaultnetwork.allowedHosts: []: No hosts beyond presets. An entry is a name, likeexample.comor*.example.com, or an IP literal, and can take a port, e.g. 127.0.0.1:8000. srt refuses loopback, unspecified, link-local, multicast, broadcast, cloud metadata, and your machine's own addresses for every name, and blackwall does the same for IP literals under"*"network.deniedHosts: []: Hosts to refuse. A name is refused under"*". An IP literal or a range, like10.0.0.0/8, is refused as a literal, and also when an allowed name resolves into it. AnallowedHostsentry wins over adeniedHostsname. A range is overridden only by that IP itself inallowedHostsfilesystem.denyRead: ["/"]: Blocks every read, thenallowReadopens what dev tools needfilesystem.allowReadopens only~/.local/binunder~/.local, and presets add their tools' folders. Version managers like mise keep tools elsewhere in it, so add their folders to your user configsrt.enableWeakerNetworkIsolation: true: On macOS, lets Go tools likeghverify TLS certificates throughcom.apple.trustd.agent, which also opens a data exfiltration path through that servicesrt.enableWeakerNestedSandbox: false: On Linux, lets the sandbox run inside Docker without privileged namespaces, which weakens isolationsrt.allowPty: true: Lets sandboxed commands open pseudo-terminals, which TUIs need
srt holds srt settings, each replacing its default. Blackwall doesn't read ~/.srt-settings.json.
A preset is what one tool needs to work in the sandbox: hosts, read paths, write denies, env vars like its cache folder, shell lines, macOS services, and a why, which --print-env prints. Each is a module in src/presets:
- Always on
- On by default
- private-network: Denies hosts in private ranges: RFC 1918, CGNAT, and IPv6 ULA. To reach one, add its IP literal with the port to
network.allowedHosts, e.g.192.168.1.10:8080 - local-network: Denies
localhostand*.localhost. To reach a local server, add it with the port tonetwork.allowedHosts, e.g.localhost:8000 - git: Your git config and global ignore files. Commit signing off, since gpg can't reach
~/.gnupg. Keeps srt's proxy login out of your credential helpers. Denies writes to.git/hooksand.git/configin--add-dirfolders, since srt covers only the current folder. Drop it only if you won't run git: with a~/.gitconfigit can't read, git refuses to start - github: GitHub, for
git,gh, and raw files, and gh's own config folder - python: PyPI, for
pipanduv, and uv's config, Python installs, and tools - node: The npm registry, and Node.js installed by fnm
- pre-commit: Its cache folder, and hook repos clone through srt's proxy
- agent-files: Denies writes to
.claude/settings.json,.claude/settings.local.json,.claude/hooks,.mcp.json,.claude/commands, and.claude/agentsin the current and--add-dirfolders: an unsandboxedclauderuns what they hold, the settings even before you trust the folder
- private-network: Denies hosts in private ranges: RFC 1918, CGNAT, and IPv6 ULA. To reach one, add its IP literal with the port to
- Off by default
- clipboard: On macOS, lets
clauderead an image you copied, e.g. a Cmd+Ctrl+Shift+4 screenshot, when you paste it. Every sandboxed command can then read what you copy, passwords included, and replace what you paste next - screenshots: Reads your screenshot folder, so a screenshot you copy in Finder and paste as its path reaches
claude. That's~/Desktop, unless you moved it withdefaults write com.apple.screencapture location ~/Screenshots, which also keeps the rest of your Desktop unreadable
- clipboard: On macOS, lets
Preset paths follow XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME, and XDG_RUNTIME_DIR when you set them.
~/.blackwall/config.json: add to the defaults, or replace them with overrideDefaults
Put your customizations in ~/.blackwall/config.json:
{
"filesystem": { "allowRead": ["~/.npmrc"] },
"srt": { "allowPty": false },
"overrideDefaults": {
"presets": ["github", "git"]
}
}- Top-level
presets,filesystem, andnetworkkeys take lists only, and they're added to the defaults. A relativefilesystem.denyReadorfilesystem.denyWriteentry applies to the current folder and every--add-dirfolder - To allow every public host, add
"*"tonetwork.allowedHosts, or launch with--allow-internetfor one run. Loopback, private ranges, andlocalhoststay denied, so add a local server with the port, e.g.127.0.0.1:8000 overrideDefaultstakespresets,network, andfilesystem, and replaces their default values. It's applied first, then the top-level lists are added- If you set
overrideDefaults.presets, keeplocal-network,private-network, andagent-files, orlocalhostand private ranges open again under"*", and the agent files become writable
.blackwall/config.json and .blackwall/.env, loaded only after --trust
Put a project's own config in .blackwall/config.json. It takes the same keys as ~/.blackwall/config.json, e.g. to read a file from another repo:
{
"filesystem": { "allowRead": ["/path/to/file"] }
}- Its lists are added to yours, and its
srtkeys andoverrideDefaultswin over yours - Only the current folder's config loads, not its parent folders'
Put a project's own env vars in .blackwall/.env:
- Its keys override
~/.blackwall/.env, and go only to the sandboxed command, soBLACKWALL_*keys there don't configureblackwall blackwallrefuses to run while.envexists without a trusted.blackwall/config.json.{}is enough
A cloned repo can ship a .blackwall/config.json that widens the sandbox, so blackwall refuses to run until you review it and run blackwall --trust. Like direnv, trust covers that path with that exact content, so run it again after every edit to config.json. Sandboxed commands can't write to ~/.blackwall, or to .blackwall in the current or --add-dir folders.
Give blackwall its own identity in Little Snitch
Every sandboxed command connects through a proxy inside blackwall, so Little Snitch sees all that traffic as node, like every other Node script. To fix that on macOS:
BLACKWALL_USE_SELF_SIGNED_NODE=1 # put this in ~/.blackwall/.env, or export itLittle Snitch then shows node-blackwall, an ad-hoc-signed copy of your node at ~/.blackwall/node-blackwall. Delete it after upgrading Node to get a fresh copy.
The question blackwall answers: you run blackwall --allow-internet claude in a repo you own or cloned, with the default config. If the agent goes rogue, is your host machine safe?
The attacker is the command inside the sandbox: a coding agent steered by a prompt injection in the repo, a malicious dependency, a tool it runs. It can run anything, for as long as the session lasts, and it can try again the next time you launch blackwall.
What blackwall defends:
- It reads and writes only what you granted, listed in Usage
- With internet access, it can only leak what it was allowed to read
Out of scope:
- Starting
blackwallwith an evil command on purpose. That's on you - What you grant:
allowRead,allowWrite,--add-dir, and a trusted.blackwall/config.jsonwith its.envcount as your own setup. Review both before--trust --trustpins onlyconfig.json. A project's.envloads whenever itsconfig.jsonis trusted, later edits included, so review it after a pull that touches it- Secrets in your shell environment,
~/.blackwall/.env, and the sandbox's agent profile. They reach the command by design - Files copied from your host agent profiles, including their symlink targets. The command can read the copies. Keep those sources outside sandbox-writable folders: later launches also follow links planted there
- Files it writes inside granted folders survive. Later sandboxed runs may read or execute them, and so does your shell when that folder is on its PATH, like an activated
.venv/bin: a plantednodethere runs your nextblackwallunsandboxed. Keep such folders off the PATH you launch from blackwallandsrtinstalled inside a writable folder, like the current folder or an--add-dirfolder. If a sandboxed command can rewrite either package, the next launch runs that code outside the sandbox.npm install -gkeeps them out
A finding counts when the sandboxed command alone gets past this, with no help from you beyond launching blackwall again. Reading host files outranks writing them, and writing outranks breaking a session.
- Hosts and paths are fixed at launch. A new host means a config edit or
--allow-internetand a relaunch, not a prompt mid-session - No credential masking yet, while Claude Code's built-in sandbox can mask secrets
Nested agent files and git hooks on Linux, HTTP proxy, and profile folder symlinks can still get past the sandbox
- On Linux, nested write denies cover matching paths found at launch, up to 3 folders below the current or
--add-dirfolder. A run can still plant.claude/settings.json,.claude/hooks,.git/hooks, or.git/configunder deeper or newly created folders, for an unsandboxedclaudeor your owngitto run later. Before runningclaudeorgitoutside the sandbox from a subfolder an agent worked in, check its.claude/and.git/ - With
HTTP_PROXYorHTTPS_PROXYset, in your shell or~/.blackwall/.env, srt sends names through that proxy and lets it resolve them, so it can't check what they resolve to. Theprivate-networkpreset,deniedHostsranges, and srt's built-in refused classes then don't apply to names. IP literals under"*"are still judged. Unset the proxy when you need those denies - On macOS, a sandboxed command can replace its own profile folder, like
~/.claude-blackwall, or~/.cache-blackwall, with a symlink. Blackwall refuses to launch when it finds one and never grants reads through it. But a session still running can swap the folder right after a second launch, say for another repo, has checked it. That launch then deletes the files it copies in, like~/.claude/CLAUDE.md, where the link points. It can't regain reads of the host folder that way. Don't start a second blackwall launch while a session you don't trust is running. Closing this needs srt to forbid unlinking a granted folder itself
Also see: TODO.md for open gaps and plans
Released under the MIT License.