# Run Claude Code in Depot sandboxes (https://depot.dev/docs/managed-agents/claude-code-self-hosted)




Run Claude Code cloud sessions in [Depot sandboxes](/docs/sandboxes/overview) through Claude's web, desktop, or mobile interface. Depot starts and manages the runner for you. View run status, timing, and failure details in your Depot dashboard.

## How it works [#how-it-works]

A [Claude Code self-hosted environment](https://code.claude.com/docs/en/self-hosted-environments) routes cloud sessions to runners on compute you choose.

Anthropic provides the Claude models and manages your conversation and session queue.

Depot creates a sandbox and starts a Claude Code runner inside it. The runner starts your session, where Claude Code runs the agent loop and tools. Claude Code connects to Anthropic for model responses and session updates.

<ClaudeCodeDiagram />

### What's the difference between Claude Code and Claude Managed Agents on Depot? [#whats-the-difference-between-claude-code-and-claude-managed-agents-on-depot]

* **Claude Code**: Use Claude's web, desktop, or mobile interface for coding tasks. Depot runs the agent loop and tools.
* **Claude Managed Agents**: Build agents for applications or automated workflows. Anthropic runs the agent loop and Depot executes commands and file operations. Follow the [Claude Managed Agents guide](/docs/managed-agents/claude-managed-agents).

## Get started [#get-started]

### Prerequisites [#prerequisites]

Before you start, you need:

* A [Depot account](/sign-up) with the **Owner** role in your Depot organization.
* A Claude Team or Enterprise plan with [self-hosted environments enabled](https://code.claude.com/docs/en/self-hosted-environments#availability-and-limitations).
* An environment key from a Claude Code self-hosted environment. Create the environment and copy its key in [Cloud environments settings](https://claude.ai/admin-settings/cloud-environments).

### Connect Claude Code to Depot [#connect-claude-code-to-depot]

1. Open [**Settings** > **Managed Runs**](/orgs/_/settings/agent-runs) in Depot and select **Claude Code**.
2. Paste your Claude Code environment key into **Environment secret**.
3. Click **Connect**.

Depot shows **Connected to Claude Code** and the **Environment pool** ID when the connection succeeds.

Depot keeps your environment key outside the sandbox. The sandbox receives a single-use credential to register its runner.

### Choose a sandbox size [#choose-a-sandbox-size]

The default sandbox size is `4x16` (4 CPUs, 16 GB memory). To change the sandbox size, open [**Settings** > **Managed Runs**](/orgs/_/settings/agent-runs) and click **Run settings** for the connection. In the **Sandbox** table, select a **Size** in the **Default** row and click **Save**. See [sandbox sizes](/docs/managed-agents/overview#sandbox-sizes) for available sizes, billing, and when changes take effect. To run on ARM64 instead of x86-64, select `arm64` under **Sandbox architecture** in the same section. See [sandbox architecture](/docs/managed-agents/overview#sandbox-architecture) for what changes. To take the Depot CI run controls away from runs, set **Depot API token role** to **Read-only** in the same section. See [limit the CLI to reading](/docs/managed-agents/overview#limit-the-cli-to-reading). To start runs without Depot Cache credentials, turn off **Depot Cache** in the same section and click **Save**. See [turn off Depot Cache for runs](/docs/managed-agents/overview#turn-off-depot-cache-for-runs).

### Authorize GitHub access [#authorize-github-access]

Each person who wants to start sessions must connect their own GitHub account to Claude.

Before you connect your account, an organization Owner must enable the GitHub connector for your Claude organization.

1. Open [**GitHub Integration** in Claude](https://claude.ai/new#customize/connectors/yours/id/integration-github).
2. Connect your own GitHub account if it isn't already connected. Use an account that has access to the repository you want to work on.
3. Follow GitHub's prompts to authorize the connection.

### Start a Claude Code session [#start-a-claude-code-session]

1. Open [Claude Code on the web](https://claude.ai/code) or the **Code** section in the Claude desktop or mobile app.
2. Click the environment name (the first control below the message box) to open the environment selector.
3. Find the environment you connected to Depot under **Self-hosted environments** and select it.
4. Click **Repo** and choose the repository you want to work on.

Now you can send Claude a task for the selected repository. For example: "Read this repository and explain how to run its tests." Claude's response appears in the same conversation.

## Verify your run in Depot [#verify-your-run-in-depot]

Open [**Managed Runs**](/orgs/_/agent-runs) in your Depot dashboard and choose **Claude Code** in the provider filter to see your runs, newest first. You can also filter by status.

![Managed Runs list filtered to Claude Code, with status filters and a list of runs](/images/docs/claude-code-agent-runs.webp)

Select a run to see its status, duration, and steps. Each step also shows its duration and its log, and the setup script step shows the script's output. If the run failed, a banner shows the reason.

The **Agent** panel shows the sandbox ID. The **Outputs** panel lists the files the run saved, which you can download. See [Save files from a run](/docs/managed-agents/overview#save-files-from-a-run).

Use **Open in Claude Code** to return to the conversation when the link is available.

![Claude Code run page showing its status, duration, steps, Outputs and Agent panels, and the Open in Claude Code button](/images/docs/claude-code-agent-run-details.webp)

To end unwanted work, stop it in Claude Code first. If a Depot run remains active afterward, organization owners can [stop that run](/docs/managed-agents/overview#stop-a-run).

## When the runner stops [#when-the-runner-stops]

After Claude Code becomes idle, its runner normally waits about five minutes before ending the run. You can send a follow-up during that time. After the sandbox stops, another message can start a new sandbox from the latest available [workspace snapshot](/docs/managed-agents/overview#session-continuity).

The idle wait and saving files use [billable compute](/docs/managed-agents/overview#billable-waiting-and-failure-cases). Pending work or approvals can keep the session active longer.

If you're done with a task that still shows as running, stop the work in Claude Code first. You can then [stop any remaining Depot run](/docs/managed-agents/overview#stop-a-run). Stopping only the Depot run can cause the provider to retry in a new sandbox.

## What's next [#whats-next]

With the connection working, give Claude Code a larger repository task: implement a feature, investigate failing tests, or prepare a refactor. The work runs on Depot without using your laptop's CPU or memory, and you can return to the conversation with follow-up instructions.

Continue working by sending another message in the same Claude Code conversation. If the session needs a new sandbox, Depot restores the latest available workspace snapshot. See [Session continuity](/docs/managed-agents/overview#session-continuity) for details and limitations.


## Documentation Index

See [llms.txt](https://depot.dev/llms.txt) for the full index of all documentation pages.