---
title: OS sandbox and network allowlist
description: What sandboxed bash can read, write and reach on macOS and Linux, and how to change its network allowlist.
section: security
order: 20
audience: [user, operator, builder]
sources: [packages/harness/src/permissions/sandbox.ts, packages/harness/src/permissions/egress.ts, packages/harness/src/permissions/egress-proxy.ts, packages/harness/src/permissions/netns.ts, cli/AGENTS.md]
features: []
---

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 {#when}

| 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 {#scope}

- **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 {#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`):

```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](/docs/security/egress.md).

## Troubleshooting {#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`).

## Related {#related}

- [Permission modes and rules](/docs/security/permissions.md)
- [Egress map](/docs/security/egress.md)
- [Organisation policy](/docs/security/policy.md): `sandbox.required` and the network ceiling.
