Sandboxes でエージェントを実行する

Give your agent a workspace where it can edit code, run tests, and save results on CoreWeave. This overview helps you choose an integration and configure the environment for longer sessions, subagents, and tool execution. スクリーンショット、マウス入力、キーボード入力を通じてグラフィカルなデスクトップを操作するエージェントについては、サンドボックスでコンピューター操作エージェントを実行するを参照してください。

Interactive coding agents and autonomous agents

With an interactive coding agent, you work alongside the agent: ask questions, review edits, and approve actions through a terminal, browser, or mobile app. For example, use Claude Code to investigate a failing test while you guide the changes. With an autonomous agent, you delegate a task and collect results later. For example, assign a repository migration, let the agent run tests and revise its changes, then review the result. Configure its permissions, credentials, and stopping conditions before starting work. It can still pause for your input when needed. These are ways of working, not separate sandbox types. A coding harness can support both. The harness manages the agent loop, model context, tool selection, and delegation. CoreWeave supplies the compute and filesystem where tools run. A longer sandbox lifetime gives the agent more execution time, but conversation compaction and task recovery depend on the harness.

Choose an integration

The following integrations execute commands in a CoreWeave sandbox. The location of the agent loop and the interface you use differ:

Guide	Agent loop runs in	You interact through	Use it to
Claude Code	The sandbox	An attached terminal, Claude’s mobile or Desktop app, or claude.ai/code	Work on a repository from your terminal or use Remote Control from another device.
Cursor	The sandbox	An attached terminal or a script	Edit a repository interactively or run unattended coding tasks.
OpenCode CLI	The sandbox	An attached terminal or a command	Run coding tasks with W&B Serverless Inference or another model provider.
Muse Code	The sandbox	The Sandbox SDK	Run a CLI task on a repository and retrieve the result.
Pi	The sandbox	An attached terminal	Work on a repository with your choice of model provider, including W&B Serverless Inference.
Claude Managed Agents	Anthropic’s managed service	The Managed Agents API	Connect a self-hosted worker to a managed agent session.
Codex	The sandbox	Codex CLI in the sandbox, a local CLI connected to Codex App Server, or desktop and paired mobile apps	Work on a remote repository with Codex.
Devin Outposts	Devin Cloud	Devin Cloud	Run Devin’s commands in a sandbox through an outpost worker.
OpenAI Agents API	OpenAI’s managed service	Your application through the Agents API	Run agent tools and subagent analyses in a self-hosted sandbox.

The Claude Code and Pi examples start an interactive agent in a workspace you manage. The Cursor examples support interactive work and unattended tasks. The Muse Code example runs a task without an interactive terminal. The Managed Agents and Devin Outposts examples start workers that reuse a sandbox across queued sessions. Ending one provider session doesn’t stop that worker sandbox. Model inference remains with the provider configured for your agent. Running tools in a sandbox doesn’t prevent the agent from sending prompts, file contents, or tool output to that provider. Review its data-handling requirements before connecting your workspace.

Build your own integration

Use the Sandbox SDK to create an environment, execute tool calls, collect results, and stop compute from your own harness. Start with command execution, file operations, and cleanup patterns.

Get started with cws-agent

cws-agent automates sandbox creation, agent installation, and workspace management. Most integration guides include a quick-start path that uses it. Other guides set up the sandbox directly with the Sandbox SDK. Where a guide documents both, you can use either path independently. インストール手順に従ってインストールしたら、インテグレーションガイドを選択してください。各ガイドの cws-agent のサンプルでは、サンドボックスへのアクセスに W&B APIキーを使用します。エージェントのプロバイダーへの認証は別途行ってください。

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

CWSANDBOX_API_KEY の設定を解除すると、cws-agent は W&B 認証を選択します。この変数を設定すると、cws-agent は CoreWeave 認証を選択します。 Sandbox SDK のサンプルはコード内で認証情報を選択するため、各ガイドに記載されている認証情報の手順に従ってください。たとえば OpenAI Agents API のレシピでは、デフォルトで CWSANDBOX_API_KEY が必要です。W&B キーが選択されるのは、--sandbox-auth wandb を渡した場合のみです。この変数の設定を解除すると、デフォルト設定での実行は失敗します。 For configuration imports, parallel sessions, and saving or restoring workspaces, see the cws-agent documentation. You don’t need cws-agent to integrate a harness directly.

Run longer sessions

The lifetime is a wall-clock limit, including startup, and can’t be extended after creation. It doesn’t guarantee that the agent finishes or recovers from interruptions. サーバーレスサンドボックスでは、max_lifetime_seconds を省略すると有効期間がデフォルトの 10 分になります。セットアップとタスクの実行に必要な時間を見込んだうえで、作成時に有効期間を明示的に設定してください。

Set a serverless sandbox lifetime

SDK のインストールと認証が完了したら、次の作成リクエストを使用して、有効期間が 24 時間のサンドボックスを作成します。Python クライアントでは wandb extra が必要です。TypeScript では W&B クライアントのエントリポイントを使用します。

Python
TypeScript

from cwsandbox import AuthStrategy, Sandbox

sandbox = Sandbox.run(
    auth=AuthStrategy.WANDB,
    placement_mode="serverless",
    container_image="python:3.12-slim",
    resources={"cpu": "4", "memory": "8Gi"},
    max_lifetime_seconds=24 * 60 * 60,
)
print(f"Sandbox ID: {sandbox.sandbox_id}")

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

const client = createSandboxClientFromEnv();
const sandbox = await client.create({
  containerImage: "python:3.12-slim",
  resources: { cpu: "4", memory: "8Gi" },
  maxLifetimeSeconds: 24 * 60 * 60,
  waitUntilRunning: false,
});
console.log(`Sandbox ID: ${sandbox.sandboxId}`);

Save the printed ID to reconnect with the SDK. The ID confirms that creation was accepted, not that startup has finished. Follow an integration guide to wait for readiness, install, and start your agent, or supply an image with your tools already installed. Both standalone creation calls leave the sandbox running after the script exits. TypeScript’s withSandbox() stops it when its callback finishes. A with Sandbox.run(...) block stops it when the block exits. Sandboxes created through an SDK Session stop when that session closes, including during process-exit cleanup. With cws-agent installed and authenticated, set the same lifetime when launching Claude Code. Replace [SANDBOX-NAME] with a cws-agent session name for your workspace. Use 1 to 40 lowercase letters, digits, or hyphens, starting with a letter or digit:

cws-agent launch [SANDBOX-NAME] --lifetime 24h --cpu 4 --memory 8Gi --permission-mode native

To keep an interactive agent running when you close your terminal, run it inside a terminal multiplexer. See the tmux guide for detach and reconnect instructions. A detached session can still wait for an approval or login.

Keep execution time and conversation state separate

A tool command’s timeout_seconds is separate from the sandbox lifetime. Give long builds and tests an appropriate command timeout. For unattended tasks, use the harness’s supported background execution and recovery features, and save intermediate results. See command timeouts and sandbox lifecycle.

Delegate work to subagents

Configure subagents in your harness. No sandbox creation flag enables subagents. For example, Claude Code includes built-in subagents. In an interactive session, ask it to split independent investigations:

Use separate subagents to inspect the API and its tests in parallel.
Have each report relevant files and findings without editing anything.
Combine their findings into an implementation plan.

To define a reusable specialist, create this file in the sandbox’s project before starting Claude Code:

.claude/agents/test-reader.md

---
name: test-reader
description: Inspect tests and report coverage gaps without editing files.
tools: Read, Grep, Glob
---
Find tests relevant to the requested change. Summarize coverage gaps and
cite the test files. Do not modify files.

Ask Claude to use test-reader for a specific task. Delegation is available by default. A permissions.deny rule for the parent agent’s Agent tool blocks delegation. For tool permissions and other options, see Claude Code subagent configuration. Subagents using one sandbox share its compute and filesystem. Size CPU and memory for concurrent tools, and avoid simultaneous edits to the same files. When workers need independent credentials or isolation, use separate sandboxes. For separate coding tasks, cws-agent parallel sessions provide separate Git worktrees within one sandbox. These are independent sessions, not harness-managed subagents or separate security boundaries.

Use tools efficiently

Prepare the environment so agents can spend time on the task:

Install recurring dependencies in the image. Pass a prepared container_image at creation to avoid installing the same test tools and runtimes for every session. See sandbox configuration.
Select the tools the task needs. Configure skills and Model Context Protocol (MCP) servers in the harness. For a CLI session managed by cws-agent, preview local configuration and import selected items into its sandbox:
cws-agent config preview [SANDBOX-NAME] --verbose cws-agent config sync [SANDBOX-NAME]
Configuration import isn’t available for Claude Managed Agents workers. The sync command prompts for selections and confirmation. Restart the agent to load the changes. Install required executables in the sandbox and replace laptop-only paths. See skills and MCP imports.
Return focused results. Have tools filter or summarize data in the sandbox before returning it to the model. For example, save full test output to a file and return failed test names and a short failure summary. Keep the file available for follow-up inspection.
Parallelize independent operations. When resources allow, run independent checks concurrently. Wait for prerequisites before dependent steps. The SDK execution guide shows how to start commands and collect results.

Tool discovery, context compaction, and decisions about which tools to call remain harness features. CoreWeave runs the commands and stores their files.

Keep results and stop compute

Exiting an agent or ending a provider session doesn’t necessarily stop its sandbox. Follow the cleanup steps in the integration guide, and set a lifetime when you create compute. 停止する前に結果をコピーしておくか、変更をリポジトリにプッシュするか、スナップショットボリュームを設定してファイルシステムスナップショットを使用してください。スナップショットで保持されるのはファイルのみで、実行中のプロセスは保持されません。なお、プロバイダー側の会話履歴は、サンドボックスとは別のライフサイクルで管理されます。

​Interactive coding agents and autonomous agents

​Choose an integration

​Build your own integration

​Get started with cws-agent

​Run longer sessions

​Set a serverless sandbox lifetime

​Keep execution time and conversation state separate

​Delegate work to subagents

​Use tools efficiently

​Keep results and stop compute