OS sandbox and network allowlist
What sandboxed bash can read, write and reach on macOS and Linux, and how to change its network allowlist.
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,~/.cacheand 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
/tmpand/runare hidden:/tmpis the session's own directory, shared by every command in the session, and/runis an empty tmpfs. - Environment: the command loses
SSH_AUTH_SOCK,VENOM_ADMIN_TOKENandVENOM_SERVER_TOKEN. The two tokens are also kept from unsandboxed bash, hooks, MCP servers and language servers.VENOM_API_KEYstays.
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 installfails with 403 from a private registry. Add the registry's host tosandbox.network.allowand 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).
Related
- Permission modes and rules
- Egress map
- Organisation policy:
sandbox.requiredand the network ceiling.