Sandboxes

What a Sandbox Adds

A sandbox is the environment a session works in: a filesystem and a shell. Every session has exactly one, and choosing it decides several things at once:

• The file and shell tools. read, write, and edit act on its files, and bash runs commands in its shell.
• Project instructions. AGENTS.md and CLAUDE.md are found by walking up from its working directory.
• Plugin tools. A plugin that works through the sandbox reaches the same files and shell.

Swap the sandbox and all of this moves with it. The agent, its tools, and your plugins stay the same.

Kinds of Sandbox

Pick the one that fits your use case. The wider the environment, the more model-directed work can read, change, run, and reach.

Choose a Sandbox

Pass --sandbox-driver when you start a session:

codework run --sandbox-driver memory "Draft a README for a CLI tool"

A session keeps its sandbox for life, so leave the flag off when you continue one with --session. Editor sessions over ACP always use your local folder.

Reuse or Attach

Start a new session in a sandbox CodeWork already created with --sandbox-id <id>. Its files are still there, and a stopped remote sandbox starts again.

To use a remote sandbox you created yourself, pass its provider ID with the driver:

codework run --sandbox-driver daytona --sandbox-provider-id <id> "Inspect the repository"

CodeWork uses an attached sandbox but never stops it.

When Sandboxes Stop

CodeWork stops the sandboxes it creates:

• codework run stops its sandbox when the run ends.
• codework serve keeps them running between sessions and stops them when the server shuts down.
• codework acp stops them when the editor disconnects.

Safety