---
title: "Run Claude Code, Codex or OpenCode in a sandbox"
description: "Start a coding agent in its own Promigence sandbox with one command, keep the model key off the command line, and drive sandboxes from Claude Code."
url: "https://www.promigence.ai/docs/guides/claude-code-and-codex"
site: "Promigence"
---

# Run Claude Code, Codex or OpenCode in a sandbox

Start a coding agent in its own Promigence sandbox with one command, keep the model key off the command line, and drive sandboxes from Claude Code.

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:

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://www.promigence.ai/docs/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:

```bash
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:

```bash
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:

```bash
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:

| Flag | Effect |
|---|---|
| `--cap USD` | The most each sandbox or batch it starts may spend |
| `--read-only` | Offer only the tools that read: listings, files, output, reports |
| `--allow-tools A,B` | Offer only the tools you name |
| `--keep` | Leave the sandboxes the session started running when the server stops |

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`:

```bash
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.