Skip to content
Docs menu

OS sandbox and network allowlist

What sandboxed bash can read, write and reach on macOS and Linux, and how to change its network allowlist.

View .md

Permission rules decide whether a command runs. The OS sandbox decides what a running command can touch. It is the boundary that holds when a rule was too broad or a model was talked into something, which is why yolo and auto use it by default.

When bash is sandboxed

Situation Sandboxed
yolo and auto modes yes (auto refuses to run without a sandbox)
plan, default, accept-edits no, unless --sandbox or the organisation policy's sandbox.required
sudo mode no, unless --sandbox
--sandbox always
--no-sandbox never (refused under a policy with sandbox.required)

macOS uses sandbox-exec with a generated Seatbelt profile. Linux uses bwrap (bubblewrap). If neither is installed, yolo's bash asks like accept-edits and a warning says so; --sandbox with no sandbox denies bash. venom doctor reports which sandbox it found.

Formatters and language servers that venom runs after edits use the same sandbox when bash does.

What a sandboxed command can do

  • Write only to the workspace, temp dirs and package caches (~/.npm, ~/.cache and similar).
  • Read everything except the secret locations the policy hard-denies: ~/.ssh, ~/.aws, ~/.config/gh, ~/.netrc, keychains and the like.
  • Connect to Unix sockets only under the workspace and its private temp dir. Container daemon sockets, the ssh agent, tmux and D-Bus are out of reach. On Linux the host's /tmp and /run are hidden: /tmp is the session's own directory, shared by every command in the session, and /run is an empty tmpfs.
  • Environment: the command loses SSH_AUTH_SOCK, VENOM_ADMIN_TOKEN and VENOM_SERVER_TOKEN. The two tokens are also kept from unsandboxed bash, hooks, MCP servers and language servers. VENOM_API_KEY stays.

Network

Sandboxed bash reaches the network only through venom's egress proxy on 127.0.0.1, started the first time a sandboxed command runs. The command gets HTTP_PROXY, HTTPS_PROXY and ALL_PROXY pointing at it, so npm, pip, go, cargo, git and curl work unchanged.

Policy What the command can reach
allowlist (default) the hosts on the list, through the proxy. On macOS nothing else is reachable, DNS included; on Linux the command runs in its own network namespace bridged to the proxy
true any host
false nothing, loopback included

The default allowlist: the npm registry, PyPI, the Go module proxy and checksum database, crates.io, GitHub over https, and your orchestrator's host. A request to anything else gets 403 from the proxy, a warning naming the host (once per host until /reload) and an audit record. The model is told too, so it doesn't retry: [venom: the sandbox's network allowlist blocked example.com:443 during this command (retrying won't get through) …].

Change it in ~/.venom/permissions.json (or $VENOM_HOME/permissions.json):

{
  "sandbox": {
    "network": {
      "allow": ["docs.rs", "*.internal.example:443", "localhost:5432"]
    }
  }
}
Key Type Default What it does
sandbox true, false or object on in yolo and auto true sandboxes bash in every mode, false turns it off (an untrusted project can turn it on, never off)
sandbox.network true, false or object allowlist true open network, false none
sandbox.network.allow list of host[:port] [] Hosts added to the defaults. A host without a port means 80 and 443. *.example.com covers subdomains
sandbox.network.defaults boolean true false drops the built-in hosts

A name that resolves to a loopback, private or link-local address is refused; allowlist the IP literal instead (127.0.0.1:5432). An untrusted project's sandbox.network can only narrow the list. An organisation policy's sandbox.network is a ceiling every other list is intersected with. Edits apply at the next /reload.

/permissions shows the effective sandbox and network policy. Every contacted host lands in the session's egress map.

Troubleshooting

  • npm install fails with 403 from a private registry. Add the registry's host to sandbox.network.allow and run /reload.
  • "the OS sandbox only allows writes to the workspace and temp dirs". Move the file into the workspace, or run without the sandbox (--no-sandbox) if you accept the risk.
  • A test needs Docker. The Docker socket is unreachable from the sandbox by design. Run that command outside yolo, where it asks and runs unsandboxed after you approve.
  • Linux: bash is denied with --sandbox. Install bubblewrap (apt install bubblewrap).