> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superserve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run coding agents in sandboxes

> Give a coding agent its own sandbox with your repository, let it edit and run code there, and read the changes back.

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](https://docs.superserve.ai/secrets/overview.md) 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

**1. Store the model API key as a secret**

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

**2. Create a sandbox from an agent template**

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

**3. Clone the repository and run the agent**

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

**4. 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](https://docs.superserve.ai/integrations/coding-agents/claude.md).

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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()
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-default"}}
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](https://docs.superserve.ai/commands/streaming.md) to watch the agent work.
* To keep the agent's work, push a branch from the sandbox, or take a [snapshot](https://docs.superserve.ai/sandbox/snapshots.md) to continue later.

## Integrations

Each integration guide shows the template, the secret, and the command for one agent. See the [coding agents](https://docs.superserve.ai/integrations/overview.md#coding-agents), such as [Claude Code](https://docs.superserve.ai/integrations/coding-agents/claude.md), [Codex](https://docs.superserve.ai/integrations/coding-agents/codex.md), and [OpenCode](https://docs.superserve.ai/integrations/coding-agents/opencode.md). To let a platform run the agent loop on a Superserve sandbox, see the [agent platforms](https://docs.superserve.ai/integrations/overview.md#agent-platforms).

## Related guides

> [card] [Secrets](https://docs.superserve.ai/secrets/overview.md)
>
> Give agents API keys without exposing them.

> [card] [Snapshots](https://docs.superserve.ai/sandbox/snapshots.md)
>
> Save a sandbox's state and continue later.

> [card] [CI workers](https://docs.superserve.ai/guides/run-ci-jobs.md)
>
> Run builds and tests in sandboxes.

> [card] [Code interpreter](https://docs.superserve.ai/guides/code-interpreter.md)
>
> Run model-generated code and read the output back.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.