Sandbox
OptiQ Code's bash and run_tests tools run commands on your machine. By default they run with your own permissions, and the approval prompt is what stands between the model and your files. Turn the sandbox on and the operating system enforces a boundary around every command the model runs, and around everything those commands start.
It is off by default, as in Claude Code, so nothing changes until you ask for it.
# for one session, in the terminal UI /sandbox # at launch, interactive or headless $ optiq code --sandbox $ optiq code --sandbox -p "fix the failing test"
To keep it on, set "sandbox": true in ~/.optiq/code/config.json or OPTIQ_SANDBOX=1. The status bar shows sandbox while it is on.
What it allows
| Access | With the sandbox on |
|---|---|
| Writes | The repository, temp, and package caches (~/.cache, ~/.npm, ~/.cargo/registry and similar). Never .git/hooks, .git/config or shell startup files, which could run code outside the sandbox later. |
| Reads | Everything except credentials: ~/.ssh, ~/.aws, ~/.gnupg, ~/.kube, ~/.docker, ~/.netrc, ~/.npmrc, ~/.pypirc, the Hugging Face token, the keychain, and OptiQ's own state in ~/.optiq. |
| Environment | Variables whose names mark them as secrets (*_API_KEY, *_TOKEN, *_SECRET, SSH_AUTH_SOCK…) are removed before the command starts. |
| Network | Only through a local proxy that checks each host against an allowlist. Loopback is open, so a test suite can start a server on 127.0.0.1. |
| File tools | write_file and edit_file stay inside the repository; read_file cannot open the credential paths. |
The network allowlist
Out of the box it holds what a coding agent needs to install dependencies and fetch code: PyPI, npm and Yarn, crates.io, the Go module proxy, GitHub, GitLab, Bitbucket and Hugging Face. pip, uv, npm, cargo, go, git and curl all use the proxy without any setup. A tool that ignores proxy settings, such as plain ssh or a database driver, cannot connect.
The proxy refuses an allowed name that resolves to a private or local address, so a host pointed at 169.254.169.254 cannot reach a cloud metadata service. It sees the hostname and nothing else: HTTPS stays end to end.
When a command reaches for a host that is not on the list, the terminal UI asks. Enter allows it for the session and runs the command again; a also saves it to your config. To add hosts up front:
{
"sandbox": true,
"sandbox_allow_domains": ["artifacts.example.com", "*.internal.example.com"]
}*.example.com matches subdomains, not example.com itself. A repository's own .optiq/code.json cannot add hosts or exclusions; only your user config and the environment can widen the sandbox.
When something is blocked
The model is told plainly that the sandbox refused the command, and why, so it can work within it instead of debugging a mystery permission error. In the terminal UI you are also asked:
- a blocked host: allow it and run the command again;
- a blocked write or read: run that one command outside the sandbox.
These questions come up in auto-approve mode too. Turning the sandbox on was a decision, and auto-approve does not undo it. A headless run (-p, -y) never asks and never leaves the sandbox; the model gets the explanation and carries on.
Commands you always want outside it can be excluded. They still go through approval:
{ "sandbox_exclude": ["docker *", "make deploy"] }Platforms
| Platform | Mechanism |
|---|---|
| macOS | sandbox-exec (Seatbelt), built in. Apple Events and LaunchServices are refused too, so a command cannot drive another app or start one outside the sandbox. |
| Linux | bwrap (bubblewrap): apt install bubblewrap or dnf install bubblewrap. Ubuntu 24.04 and later restrict unprivileged user namespaces, which bwrap needs; allow them or add an AppArmor profile for bwrap. |
| Windows | Not available. /sandbox says so and commands run as before. |
The Lab's python and terminal tools use the same sandbox code, with a stricter policy: a scratch directory and no network at all. One sandbox serves both, so an improvement to one is an improvement to the other.
What it does not do
It reduces what a misbehaving or manipulated model can reach. It is not a VM. An allowed host is reachable for anything: allowing github.com also allows pushing data to it. Package installs run the package's own install scripts inside the sandbox, with the sandbox's rules. And a command run outside it, through an exclusion or an approved retry, runs with your full permissions.