Run Claude Code in a CoreWeave sandbox

Run Claude Code inside a CoreWeave sandbox and interact with it from your terminal. This guide covers launching the agent, working on a repository, retrieving a result, and stopping the sandbox. Claude’s model requests still go to your configured model provider.

CoreWeave Serverless sandboxes are in public preview.

Prerequisites

Before you begin, you need the following:

A Weights & Biases (W&B) API key. These examples use W&B authentication. For other credentials, see Choose a credential.
A Claude account or API credentials supported by Claude Code.
A repository URL the sandbox can clone. The examples use a public repository. Private repositories require Git credentials inside the sandbox.

Export your W&B API key in the terminal where you run this guide. Unset any CoreWeave token so cws-agent selects W&B authentication:

export WANDB_API_KEY="[WANDB-API-KEY]"
unset CWSANDBOX_API_KEY

W&B users don’t need the SANDBOX_USER IAM action. That permission applies only when authenticating with a CoreWeave API access token.

Quick start with cws-agent

Follow the cws-agent installation instructions. The tool configures a snapshot volume to save and restore your workspace with file system snapshots. To use an Anthropic API key, load it into ANTHROPIC_API_KEY in your local terminal before launching or restoring the sandbox. cws-agent passes this variable into the sandbox. API-key authentication doesn’t require browser sign-in. See Claude Code authentication. Replace [SANDBOX-NAME] with a cws-agent session name for this workspace and [REPOSITORY-URL] with the repository to clone. For the session name, use 1 to 40 lowercase letters, digits, or hyphens, starting with a letter or digit:

cws-agent launch [SANDBOX-NAME] --repo-url [REPOSITORY-URL] --permission-mode native

Claude Code opens in the sandbox’s project directory. Follow any workspace trust prompts. For API-key authentication, approve the key when prompted. If you need account authentication, exit Claude and run cws-agent login [SANDBOX-NAME], then complete /login there. The --permission-mode native option uses Claude’s own approval settings. Without it, cws-agent defaults to bypassing those approval prompts. See permission modes. If Claude reports Not logged in despite a configured API key and never offers to approve it, exit with /exit, then reconnect with onboarding enabled:

cws-agent connect [SANDBOX-NAME] --cmd 'unset IS_DEMO; exec claude'

This command uses Claude’s native approval settings. Accept the workspace trust and API-key prompts before continuing. Ask Claude to create a file you can check afterward:

Create sandbox-proof.txt in the current directory containing "Hello from CoreWeave", then read it back.

Exit Claude with /exit. From your local terminal, read the file and save the workspace before stopping compute:

cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'
cws-agent down [SANDBOX-NAME]

The file should contain Hello from CoreWeave. down takes a snapshot and stops the sandbox. Exiting Claude alone leaves it running. If the snapshot fails, inspect cws-agent status [SANDBOX-NAME] and retry after resolving the failure. If you can discard unsaved changes, use cws-agent down [SANDBOX-NAME] --no-snapshot. To return to the saved workspace, run:

cws-agent restore [SANDBOX-NAME] --connect --permission-mode native

For saved conversations and parallel worktrees, see the cws-agent sessions guide.

Set up with the Sandbox SDK

Run Python snippets in the virtual environment below. Save TypeScript snippets as .mts files in the project where you install the client, then run them with npx tsx [FILENAME].mts. Use this path to manage the sandbox directly. It’s independent of cws-agent and doesn’t configure snapshots.

Create the sandbox

Choose a client and install it locally:

Python
TypeScript

Use Python 3.11 or later and uv:

uv venv --python 3.11
source .venv/bin/activate
uv pip install 'cwsandbox[wandb]>=1.14.2'

Use Node.js 22 or later. Install the client and TypeScript runner in your project:

npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx

Save the script for your language using the filename shown. It creates a serverless sandbox, installs Claude Code, and clones the repository passed on the command line. If setup fails, it stops the sandbox before raising the error.

Python
TypeScript

create_claude_sandbox.py

import sys

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.run(
    auth=AuthStrategy.WANDB,
    container_image="node:22-bookworm",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=4 * 3600,
    tags=["claude-code-cli"],
)
try:
    sandbox.wait()
    commands = [
        ["bash", "-o", "pipefail", "-ec", "curl -fsSL https://claude.ai/install.sh | bash"],
        ["mkdir", "-p", "/workspace"],
        ["git", "clone", "--", sys.argv[1], "/workspace/project"],
    ]
    for command in commands:
        result = sandbox.exec(command, timeout_seconds=900).result()
        if result.returncode != 0:
            raise RuntimeError(result.stderr or result.stdout)
except BaseException:
    sandbox.stop().result()
    raise

print(f"Sandbox ID: {sandbox.sandbox_id}")

create_claude_sandbox.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

const repository = process.argv[2];
if (!repository) throw new Error("Pass a repository URL.");

const client = createSandboxClientFromEnv();
const sandbox = await client.create({
  containerImage: "node:22-bookworm",
  resources: { cpu: "2", memory: "4Gi" },
  maxLifetimeSeconds: 4 * 3600,
  waitUntilRunning: false,
  tags: ["claude-code-cli"],
});
try {
  await sandbox.wait();
  const commands = [
    ["bash", "-o", "pipefail", "-ec", "curl -fsSL https://claude.ai/install.sh | bash"],
    ["mkdir", "-p", "/workspace"],
    ["git", "clone", "--", repository, "/workspace/project"],
  ];
  for (const command of commands) {
    await sandbox.commands.run(command, { timeoutMs: 900_000, check: true });
  }
} catch (error) {
  await sandbox.stop();
  throw error;
}
console.log(`Sandbox ID: ${sandbox.sandboxId}`);

Replace [REPOSITORY-URL] with your repository URL, then run the script:

Python
TypeScript

python create_claude_sandbox.py [REPOSITORY-URL]

npx tsx create_claude_sandbox.mts [REPOSITORY-URL]

Record the printed sandbox ID. The sandbox continues running after the script exits, until you stop it or its 4-hour lifetime expires.

Open Claude Code

Use the SDK to attach your local terminal with W&B authentication. The script forwards keystrokes to a sandbox shell and restores your terminal when the shell exits.

Python
TypeScript

On macOS or Linux, save this as attach_sandbox.py:

attach_sandbox.py

import os
import shutil
import sys
import termios
import threading
import tty

from cwsandbox import AuthStrategy, Sandbox

if not sys.stdin.isatty() or not sys.stdout.isatty():
    raise SystemExit("Run this script in an interactive terminal.")

sandbox = Sandbox.from_id(sys.argv[1], auth=AuthStrategy.WANDB).result()
size = shutil.get_terminal_size()
terminal = sandbox.shell(["/bin/bash"], width=size.columns, height=size.lines)
fd = sys.stdin.fileno()
saved = termios.tcgetattr(fd)


def forward_input():
    while data := os.read(fd, 1024):
        terminal.stdin.write(data).result()
    terminal.stdin.close().result()


try:
    tty.setraw(fd)
    threading.Thread(target=forward_input, daemon=True).start()
    for chunk in terminal.output:
        sys.stdout.buffer.write(chunk)
        sys.stdout.buffer.flush()
    result = terminal.result()
finally:
    termios.tcsetattr(fd, termios.TCSADRAIN, saved)
    terminal.stdin.close().result()

raise SystemExit(result.returncode)

Save this as attach_sandbox.mts:

attach_sandbox.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

if (!process.stdin.isTTY || !process.stdout.isTTY) {
  throw new Error("Run this script in an interactive terminal.");
}
const sandboxId = process.argv[2];
if (!sandboxId) throw new Error("Pass a sandbox ID.");
const client = createSandboxClientFromEnv();
const sandbox = await client.fromId(sandboxId);
const terminal = await sandbox.shell({
  command: ["/bin/bash"],
  cols: process.stdout.columns,
  rows: process.stdout.rows,
});
const wasRaw = process.stdin.isRaw;
const forwardInput = (chunk: Buffer) => {
  void terminal.stdin.write(chunk).catch((error) => {
    console.error(error);
    void terminal.cancel();
  });
};

try {
  process.stdin.setRawMode(true);
  process.stdin.on("data", forwardInput);
  process.stdin.resume();
  for await (const chunk of terminal.output) {
    process.stdout.write(chunk);
  }
  const result = await terminal.wait();
  process.exitCode = result.exitCode;
} finally {
  process.stdin.off("data", forwardInput);
  process.stdin.setRawMode(wasRaw);
  process.stdin.pause();
  await terminal.stdin.close();
}

Replace [SANDBOX-ID] with the printed ID, then run:

Python
TypeScript

python attach_sandbox.py [SANDBOX-ID]

npx tsx attach_sandbox.mts [SANDBOX-ID]

For a sandbox created with a CoreWeave API access token, cwsandbox sh [SANDBOX-ID] is an optional shortcut. Install the cli extra to use it. It requires CWSANDBOX_API_KEY and does not accept W&B keys. For API-key authentication, enter the key in the sandbox’s Bash shell before starting Claude. The input is hidden and isn’t included in the command history:

read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
printf '\n'

Inside the sandbox, start Claude from the cloned repository:

cd /workspace/project
/root/.local/bin/claude

Approve the API key, or complete account sign-in if you aren’t using a key, then accept the workspace trust prompts. Ask Claude to create the sandbox-proof.txt file using the prompt from the quick start. When prompted, approve the file write.

Retrieve the result and stop

Exit Claude with /exit, then exit the sandbox shell with exit. From your local terminal, read the file through the SDK. Replace [SANDBOX-ID] with the printed ID:

Python
TypeScript

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.from_id("[SANDBOX-ID]", auth=AuthStrategy.WANDB).result()
result = sandbox.exec(["cat", "/workspace/project/sandbox-proof.txt"], check=True).result()
print(result.stdout, end="")

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClientFromEnv();
const sandbox = await client.fromId("[SANDBOX-ID]");
const result = await sandbox.commands.run(["cat", "/workspace/project/sandbox-proof.txt"], { check: true });
process.stdout.write(result.stdout);

Confirm that the output contains Hello from CoreWeave, then stop the sandbox:

Python
TypeScript

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.from_id("[SANDBOX-ID]", auth=AuthStrategy.WANDB).result()
sandbox.stop().result()

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

const client = createSandboxClientFromEnv();
const sandbox = await client.fromId("[SANDBOX-ID]");
await sandbox.stop();

This SDK example has no persistent mount. For larger results, use file operations. For a workspace you can restore into a new sandbox, configure file system snapshots at creation.

Troubleshoot

Use these checks to resolve common issues:

If sandbox creation fails, check your W&B API key and authentication settings. Only CoreWeave API access tokens require the SANDBOX_USER IAM action.
If installation, cloning, or model requests fail, check outbound connectivity and the relevant provider credentials. For CoreWeave Kubernetes Service (CKS) placement, your runner’s policy must permit those destinations.
If the terminal disconnects, attach again while the sandbox is running. To retain a process across terminal disconnects, run it in a terminal multiplexer such as tmux.

Next steps

For more information, see these guides:

Interactive shells and TTY covers terminal access from the SDK.
Sandbox lifecycle covers waiting, reconnecting, and stopping.
Claude Code documentation covers agent configuration and authentication.

​Prerequisites

​Quick start with cws-agent

​Set up with the Sandbox SDK

​Create the sandbox

​Open Claude Code

​Retrieve the result and stop

​Troubleshoot

​Next steps

Prerequisites

Quick start with cws-agent

Set up with the Sandbox SDK

Create the sandbox

Open Claude Code

Retrieve the result and stop

Troubleshoot

Next steps