Run Claude Code, Codex or OpenCode in a sandbox

A coding agent with shell access will install packages, rewrite files and run whatever its plan says. On your laptop that touches your real home directory and your real credentials. In a sandbox it touches a computer you can throw away.

Promigence starts Claude Code, Codex or OpenCode in a new sandbox with one command. This guide covers that command, how the model key gets in without appearing on a command line, and the other direction: letting Claude Code on your machine start and use sandboxes through MCP.

Before you start#

Install the CLI and sign in:

npm i -g promigence
promigence login
promigence doctor

doctor checks the install, the key and the connection, and says how to fix whatever fails.

Start an agent#

export ANTHROPIC_API_KEY=...        # already set in most setups
promigence agent start claude --key-from-env ANTHROPIC_API_KEY --cap 2

Three agents are supported: claude, codex and opencode. The agent runs in a fresh sandbox started from promigence/base, and it is installed there if the snapshot does not already have it.

--key-from-env VAR stores the key from that environment variable as a Promigence secret first, so the value never appears in your shell history or a process listing. After the first time, the stored secret is enough. By default the command looks for a secret called ANTHROPIC_API_KEY (OPENAI_API_KEY for codex). If yours has another name, pass --key-secret NAME; --key-secret NAME=VAR hands it to the agent under the variable VAR.

For Codex:

promigence agent start codex --key-from-env OPENAI_API_KEY --cap 2

Work on a repository#

--repo URL clones a public repository and starts the agent inside it:

promigence agent start claude \
  --repo https://github.com/your-org/your-public-repo \
  --cap 2 --timeout 2h

Private code works differently. Connect GitHub once with promigence github connect, build a snapshot of the repository with its dependencies installed and a check that must pass, then start the agent from that snapshot:

promigence snapshot create --repo your-org/app --ref main \
  --setup "npm ci && npm run build" --verify "npm test" \
  --alias app --wait

promigence agent start claude --snapshot app --cap 2

Starting from a snapshot means the agent's first command runs in a tree that is already installed and built, and every agent you start from it begins in the same verified state. The build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size (quickstart), and agents started from the snapshot pay no further build charge.

Interactive or headless#

There are two ways to work with the agent once it is up. Without extra flags, the command prints the command that opens the agent's terminal, so you can connect when you are ready; --attach opens it straight away.

With --prompt, the agent works on a task on its own, in the background:

promigence agent start claude --snapshot app \
  --prompt "Fix the failing date-parsing test in src/time and explain the change in NOTES.md" \
  --cap 3 --timeout 1h

While it works, promigence sandbox info SID shows the sandbox's state, its time left, its cost so far and the commands it ran. When it is done, copy the results out and end the sandbox:

promigence files get /work/NOTES.md ./NOTES.md --sandbox SID
promigence sandbox kill SID

Limits that keep an agent in bounds#

Every agent start takes a spend cap. --cap is in US dollars and is the most the sandbox may spend; without it the value of PROMIGENCE_SPEND_CAP applies, or your organization's default cap. --timeout sets how long the sandbox lives (one hour unless you say otherwise). An agent that loops forever stops at whichever limit it reaches first.

Want to keep the result? promigence sandbox snapshot SID --alias after-fix saves the sandbox as a new snapshot, and later sandboxes start from that point. A sandbox that was given a secret is refused here unless you pass --force, because the snapshot could then contain the secret's value. The model key counts, so think twice before forcing it.

The other direction: Claude Code drives sandboxes#

Run Claude Code on your own machine and give it sandboxes as a tool:

claude mcp add promigence -- promigence mcp

On Windows, end it with -- cmd /c promigence mcp. Claude Code can then start sandboxes, run commands in them and read files and reports through the MCP server. A few flags shape what it may do:

Sandboxes the session started end when the server stops, unless you pass --keep. To put the flags on the server, add them after promigence mcp:

claude mcp add promigence -- promigence mcp --cap 1

Teach the agent the CLI#

For the agent itself, promigence agent-guide prints a short guide to the CLI. With --install, the same command writes it into AGENTS.md or CLAUDE.md and the agent rule folders it finds, so the next session already knows the commands. Run it with --check first to see what it would change.

Checklist#

1. Store the model key once with --key-from-env, never on a command line.
2. Build a snapshot of private repositories and start agents from it.
3. Set --cap and --timeout on every agent.
4. Read progress with sandbox info, copy results out with files get.
5. End the sandbox with sandbox kill when the work is out.