Blackwall

Opinionated lightweight sandbox for daily dev tasks with coding agents. Built on Anthropic's sandbox-runtime (srt).

This project is named after the Blackwall in Cyberpunk 2077, a firewall NetWatch built to keep rogue AIs out of the Net.

Why Blackwall

Blackwall is an out-of-the-box sandbox for long-running agent tasks, mainly claude and codex. You get nearly the same experience as your daily dev work outside a sandbox, but much safer. At least the blast radius stays under control. Unlike the built-in sandboxes, it runs the whole agent inside srt, hooks and MCP servers included.

What You Give Up

• Hosts and paths are fixed at launch. A new host means a config edit or --allow-internet and a relaunch, not a prompt mid-session
• No credential masking yet, while Claude Code's built-in sandbox can mask secrets

Installation

Needs Node.js 22.21 or later.

npm install -g blackwall-sandbox

Keep blackwall and srt outside every writable folder, including the current folder and any --add-dir folder. If a sandboxed command can rewrite either package, the next launch runs that code outside the sandbox.

mkdir -p $ZSH_CUSTOM/completions
blackwall --completion zsh > $ZSH_CUSTOM/completions/_blackwall  # run it again after upgrading blackwall

Usage

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 your LAN
blackwall npm test                            # any command works, not only claude
blackwall --print-config claude               # show the merged config, after your config and the launch-time grants
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 usage

By default, a sandboxed command:

• Writes only to the current folder, --add-dir folders, /tmp/claude, and ~/.cache-blackwall
• Never writes .git/config or .git/hooks, in the current or --add-dir folders. git remote add, git config, and git branch -m fail; git push -u, git branch -D, and git switch -c lose their tracking update. Set remotes and upstreams on the host, or push with git push origin HEAD
• Never writes .claude/settings.json, .claude/settings.local.json, .claude/hooks, .mcp.json, .claude/commands, or .claude/agents in the current or --add-dir folders. The names come from the agent-files preset. A sandboxed claude can't save project permission rules either
• Reads only those folders, plus the allowRead paths in the default config and presets
• Connects only to the hosts in presets, and the ones Claude Code or Codex needs

Claude Code

blackwall claude uses ~/.claude-blackwall as its config folder instead of ~/.claude. For security, a sandboxed run never writes to ~/.claude, and reads only ~/.claude/plugins.

• Every launch copies your CLAUDE.md, rules, skills, agents, commands, and output-styles from ~/.claude, replacing what was there, so edits to those copies don't last
• Your plugins load from ~/.claude/plugins read-only, without auto-update. Sandboxed sessions follow the plugin versions installed outside
• Sessions, settings, and login stay separate
• settings.json starts with only your enabledPlugins, since your other settings, like hooks and permissions, assume no sandbox. After that it's yours to edit

Log in with /login, or put CLAUDE_CODE_OAUTH_TOKEN in ~/.blackwall/.env.

Codex

blackwall codex uses ~/.codex-blackwall as its config folder instead of ~/.codex. A sandboxed run never writes to ~/.codex, and reads only ~/.codex/packages, where the standalone installer puts the codex binary.

• Every launch copies your AGENTS.md and agents from ~/.codex, plus skills from ~/.agents. These copies replace what was there, so edits to them 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.

Agent Skill

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 -g

Configuration

Environment Variables

Put your env vars in ~/.blackwall/.env if you need them.

GH_TOKEN=xxx                  # generate a read-only PAT from https://github.com/settings/personal-access-tokens
CLAUDE_CODE_OAUTH_TOKEN=xxx   # run `claude setup-token` to get one

Sandboxed commands get BLACKWALL_SANDBOX=1, so a script can tell it runs inside blackwall.

Default

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.

• presets: ["agent-files", "python", "node", "github", "git", "pre-commit", "local-network", "private-network"]: The presets on by default
• network.allowedHosts: []: No hosts beyond presets. An entry is a name, like example.com or *.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. blackwall applies the same to IP literals under "*". These aren't in --print-config
• network.deniedHosts: []: Hosts to refuse. A name is refused under "*"; without "*", an unlisted host is refused anyway. An IP literal or a range, like 10.0.0.0/8, is refused as a literal, and also when an allowed name resolves into it. An allowedHosts entry wins over a deniedHosts name. A range is overridden only by that IP itself in allowedHosts
• filesystem.denyRead: ["/"]: Blocks every read, then allowRead opens what dev tools need
• filesystem.allowRead opens only ~/.local/bin under ~/.local, and presets add their tools' folders. Version managers like mise keep tools elsewhere in it, so add their folders to your user config
• srt.enableWeakerNetworkIsolation: true: On macOS, lets Go tools like gh verify TLS certificates through com.apple.trustd.agent, which also opens a data exfiltration path through that service. On by default because the github preset is
• srt.enableWeakerNestedSandbox: false: On Linux, lets the sandbox run inside Docker without privileged namespaces, which considerably weakens isolation
• srt.allowPty: true: Lets sandboxed commands open pseudo-terminals, which TUIs need

srt holds srt settings, passed to srt untouched, each replacing its default. Blackwall doesn't read ~/.srt-settings.json, only the srt CLI does.

Presets

A preset is what one tool needs to work in the sandbox: hosts, read paths, env vars like its cache folder, shell lines, macOS services, and a why, which blackwall --print-env prints above the preset's env vars and shell lines. Each is a module in src/presets:

• Always on
  • mac: System paths macOS tools need. On macOS
  • linux: System paths Linux tools need, and /tmp. On Linux
  • tmpdir: /tmp/claude as the temp folder
• On by default
  • private-network: Denies LAN hosts: RFC 1918, CGNAT, and IPv6 ULA ranges. To reach one, add its IP literal with the port to network.allowedHosts, e.g. 192.168.1.10:8080
  • local-network: Denies localhost and *.localhost. To reach a local server, add it with the port to network.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/hooks and .git/config in --add-dir folders. Drop it only if you won't run git: with a ~/.gitconfig it can't read, git refuses to start
  • github: GitHub, for git, gh, and raw files, and gh's own config folder
  • python: PyPI, for pip and uv, 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/agents in the current and --add-dir folders: an unsandboxed claude runs what they hold, even before you trust the folder. Drop it and a sandboxed command can plant commands that run on the host
• Off by default
  • clipboard: On macOS, lets claude read 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 with defaults write com.apple.screencapture location ~/Screenshots, which also keeps the rest of your Desktop unreadable

tmpdir, mac, and linux aren't in the presets list, so overriding it can't drop them.

Preset paths follow XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, and XDG_CACHE_HOME when you set them.

User Config

{
  "filesystem": { "allowRead"