Run coding agents in sandboxes

A coding agent reads a repository, edits files, and runs commands such as tests and package installs. Run it in a sandbox, not on your laptop or your server. The agent gets a full Linux machine to work in, and its commands can’t touch anything outside that machine.

Why use a sandbox

Isolation: the agent can install packages and run any command. A wrong command breaks only the sandbox, which you delete.
Keys stay out of the sandbox: a secret gives the agent its model API key as a stand-in token. Superserve adds the real key only on requests to the provider.
One sandbox per task: run many agents at the same time, each on its own branch in its own sandbox.
Ready to start: public templates such as superserve/claude-code include the agent CLI, git, and common tools.

How it works

Store the model API key as a secret

Create the secret once. The sandbox gets a stand-in token, not the key.

Create a sandbox from an agent template

Bind the secret to the environment variable that the agent reads.

Clone the repository and run the agent

Run the agent’s non-interactive mode with commands.run.

Read the changes back

Read git diff, run the tests, or push a branch. Then delete the sandbox.

Run Claude Code on a repository

This example clones a repository, asks Claude Code to add a file, and prints the changes. Create the anthropic-key secret first, as shown in Claude Code.

import { Sandbox } from "@superserve/sdk"

const sandbox = await Sandbox.create({
  name: "coding-task",
  fromTemplate: "superserve/claude-code",
  secrets: { ANTHROPIC_API_KEY: "anthropic-key" },
})

await sandbox.commands.run(
  "git clone --depth 1 https://github.com/octocat/Hello-World repo",
  { timeoutMs: 60_000 },
)

const task = "Add a Python file hello.py that prints Hello, World. Don't change the README."
const agent = await sandbox.commands.run(
  'claude -p "$TASK" --permission-mode acceptEdits',
  { cwd: "/home/user/repo", env: { TASK: task }, timeoutMs: 600_000 },
)
console.log(agent.stdout)

const changes = await sandbox.commands.run(
  "git status --short && git diff",
  { cwd: "/home/user/repo" },
)
console.log(changes.stdout) // ?? hello.py

await sandbox.kill()

from superserve import Sandbox

sandbox = Sandbox.create(
    name="coding-task",
    from_template="superserve/claude-code",
    secrets={"ANTHROPIC_API_KEY": "anthropic-key"},
)

sandbox.commands.run(
    "git clone --depth 1 https://github.com/octocat/Hello-World repo",
    timeout_seconds=60,
)

task = "Add a Python file hello.py that prints Hello, World. Don't change the README."
agent = sandbox.commands.run(
    'claude -p "$TASK" --permission-mode acceptEdits',
    cwd="/home/user/repo",
    env={"TASK": task},
    timeout_seconds=600,
)
print(agent.stdout)

changes = sandbox.commands.run(
    "git status --short && git diff",
    cwd="/home/user/repo",
)
print(changes.stdout)  # ?? hello.py

sandbox.kill()

The task goes in through the TASK environment variable, so quotes and other shell characters in it reach the agent unchanged.
--permission-mode acceptEdits lets Claude Code edit files without a prompt. Give more permissions only for commands that the task needs.
Agents can work for many minutes. Give commands.run a timeout that is longer than the task, or stream the output to watch the agent work.
To keep the agent’s work, push a branch from the sandbox, or take a snapshot to continue later.

Integrations

Each integration guide shows the template, the secret, and the command for one agent. See the coding agents, such as Claude Code, Codex, and OpenCode. To let a platform run the agent loop on a Superserve sandbox, see the agent platforms.

Secrets

Give agents API keys without exposing them.

Snapshots

Save a sandbox’s state and continue later.

CI workers

Run builds and tests in sandboxes.

Code interpreter

Run model-generated code and read the output back.

​Why use a sandbox

​How it works

​Run Claude Code on a repository

​Integrations

​Related guides