Sandboxes and safety

A sandbox runs an agent inside a Docker container that sees only its project files. Use one when you let agents work without asking you. This page shows what a sandbox allows and how to turn it on.

Diagram: an agent in a container that sees only the layer’s worktree Figure: In a sandbox, the agent sees only the worktree, mounted at /workspace.

What an agent in a sandbox can reach

	Inside the sandbox
Files	Only the layer’s worktree, at `/workspace`. It can read and change these files. No other folder of yours is there.
Network	None, unless the project’s setup allows it.
Environment	Only the variables the setup names, such as an API key.
Rights	No admin rights: all Linux capabilities are dropped. On a Mac, the agent runs as the worktree’s owner, not as root.
Cuewire	The `cuewire` command, read-only. The agent can still give and take tasks, use its notes, and tell you when it needs you.
Lifetime	The container is removed when the agent exits.

A worktree is the copy of your project that a layer works in. On the base layer, it is your project folder.

The sandbox applies to agents, not to a plain Shell. It is for projects on this computer, not on remote ones.

Turn on a sandbox

You need Docker on this computer, and an image that has your agents’ programs installed (for example Claude Code and Codex). Cuewire does not publish such an image yet.

Build or choose an image with your agents in it, for example my-agents:latest.

In your project, create the file .cuewire/layers.toml and add a [sandbox] section:

[sandbox]
image = "my-agents:latest"
network = "bridge"
env = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"]

Restart your agents: right-click each one and choose Restart. Each agent now starts in its own container.

The settings:

Setting	What it does
`image`	The Docker image to run.
`devcontainer`	Use your project’s dev container instead of `image` (see below). Use one or the other.
`network`	`"none"` (the default): no network. `"bridge"`: the agent can reach the internet, for example its model’s API.
`env`	The names of variables to pass in. Only these reach the agent.

Note

On Windows, agents in a sandbox reach Cuewire over Docker’s network. Set network = "bridge". Without it, the agent won’t start, and its node tells you to add it.

The container can’t see your login files. That is the point. Agents sign in with variables you pass in by name, in env:

Claude Code: CLAUDE_CODE_OAUTH_TOKEN (from claude setup-token) or ANTHROPIC_API_KEY.
Codex: OPENAI_API_KEY.

Use your project’s dev container

If your project has a dev container, the sandbox can use it instead of an image:

[sandbox]
devcontainer = ".devcontainer/devcontainer.json"
network = "bridge"
env = ["ANTHROPIC_API_KEY"]

Cuewire uses the dev container’s image, or builds its Dockerfile when the agent starts. The build’s progress shows in the agent’s terminal.
Cuewire leaves out settings that would widen the sandbox, such as extra mounts and admin rights. It also skips start-up commands, such as postCreateCommand. The agent’s terminal says which settings were left out.
Dev container features don’t run. Install the agent’s program in the Dockerfile.

Warning

Building a Dockerfile always has network access, whatever network says. A Dockerfile can download things, and it can send out files from the project. It gets nothing else of yours.

When the sandbox setup changes

An agent in a sandbox can change files in its worktree, including .cuewire/layers.toml, the dev container and its Dockerfile. So Cuewire remembers the setup that agents first started with in each project.

When the setup changes, for example the network is opened or another variable is passed in, agents in that project don’t start. Their nodes say that the sandbox setup changed.

An agent held because its project’s sandbox setup changed Figure: The setup changed, so the agent waits for you.

To go on:

Look at what changed in .cuewire/layers.toml, the dev container or the Dockerfile.
If you agree with it, press Ctrl+K (Cmd+K on a Mac) and run Trust this project’s sandbox setup. Cuewire says “Agents in this project now start with its current sandbox setup.”
Right-click each waiting agent and choose Restart.

All layers of a project share one trusted setup.

The command palette with Trust this project’s sandbox setup Figure: Trust the new setup only after you have read the change.

Skip permission prompts and the sandbox

In a sandbox, it is safer to let an agent work without asking: it can only touch its worktree. To turn this on, see Skip permission prompts.

Without a sandbox, the agent sheet warns you when you turn skipping on. Your organisation can go further. With the policy Skip permission prompts only in a sandbox, an agent with skipping on won’t start outside a sandbox. Its node says: “your organisation allows skipping permissions only inside a sandbox; add a [sandbox] to .cuewire/layers.toml or turn skipping off”. See Teams and organisations.

Other ways Cuewire keeps you safe

Wires: an agent can reach only the agents, notes and portals it is wired to. See Agents working together.
Read-only roles: a role can hold an agent to reading only. See Roles, models and options.
Approvals: you see every question in the Needs you rail. See Know when an agent needs you.
The agents’ own rules: this computer’s Claude Code or Codex settings may forbid running without asking. Cuewire then won’t start the agent that way, and says why.

Cuewire User Guide