For an integration where Anthropic manages the agent loop and a sandbox executes tools, see Claude Managed Agents.
Prerequisites
Before you begin, you need the following:- W&B APIキー。これらのサンプルでは W&B 認証を使用します。
- ターミナルインターフェースを使用する場合は、Claude アカウント、または Claude Code がサポートする API 認証情報が必要です。Remote Control を使用する場合は、Claude Pro、Max、Team、または Enterprise のサブスクリプションが必要です。APIキーや
claude setup-tokenのトークンでは Remote Control を認証できません。 - サンドボックスからクローンできるリポジトリの URL。サンプルでは公開リポジトリを使用します。プライベートリポジトリを使用する場合は、サンドボックス内に Git の認証情報が必要です。
cws-agent が W&B 認証を選択するよう、CoreWeave トークンが設定されている場合は解除してください。
cws-agent, use --lifetime 24h. In the software development kit (SDK) examples, set Python’s max_lifetime_seconds or TypeScript’s maxLifetimeSeconds to 24 * 3600.
Quick start with cws-agent
Choose this setup path to create the sandbox withcws-agent. To create it directly with a client library, skip to Set up with the Sandbox SDK. Both paths support either interface.
cws-agent のインストール手順に従ってください。このツールは、ファイルシステムスナップショットによるワークスペースの保存と復元に使用するスナップショットボリュームを設定します。
Before Claude opens, cws-agent may show a preview of local skills and Model Context Protocol (MCP) servers to import. For this guide, press Enter at the import prompt to skip it. You can configure imports later using the agent tools guidance.
Choose one of the following interfaces. Replace [SANDBOX-NAME] with a cws-agent session name and [REPOSITORY-URL] with a public repository URL. Use 1 to 40 lowercase letters, digits, or hyphens for the session name, starting with a letter or digit.
Use the terminal interface
To use an Anthropic API key, load it intoANTHROPIC_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.
Launch Claude Code and connect your local terminal:
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:
Use Remote Control
Create a detached sandbox, then connect your terminal for subscription sign-in:IS_DEMO to enable onboarding. See Claude Code environment variables.
Inside Claude, complete /login with your Claude subscription account and accept the project trust prompt. Run /remote-control and accept its first-use confirmation, then exit Claude with /exit. Complete this step interactively to answer the confirmation before you start the detached server.
From your local terminal, start Remote Control with Claude’s own approval settings:
tmux session in the same sandbox. The cws-agent rc command redirects output to the log, so attaching to its existing session doesn’t display the prompts.
From your local terminal, stop the waiting server and open a replacement session:
tmux, start Remote Control so its sessions use the project directory:
tmux instead of updating the log. To return, run cws-agent connect [SANDBOX-NAME] --cmd 'tmux attach -t cws-remote-control'.
Set up with the Sandbox SDK
Use this alternative to create a sandbox for either interface with the Sandbox SDK. It doesn’t depend oncws-agent or configure snapshots.
Run Python snippets in the virtual environment created in this guide. Save TypeScript snippets as .mts files in the project where you install the client, then run them with npx tsx [FILENAME].mts.
Create the sandbox
Choose a client and install it locally:- Python
- TypeScript
Python 3.11 以降と
uv を使用します。tmux, then clones the repository you pass on the command line.
Both scripts require the container to run as root to install packages with apt-get and use /root/.local/bin/claude. Your runner’s policy must allow that user.
- Python
- TypeScript
create_claude_sandbox.py
[REPOSITORY-URL] with your public repository URL:
- Python
- TypeScript
Session or context manager changes that cleanup behavior.
Attach your terminal
SDK を使用し、W&B 認証を利用してローカルターミナルをサンドボックスにアタッチします。このスクリプトはキー入力をサンドボックスのシェルに転送し、シェルが終了するとターミナルを元の状態に戻します。- Python
- TypeScript
macOS または Linux では、次の内容を
attach_sandbox.py として保存します。attach_sandbox.py
[SANDBOX-ID] with the printed ID, then run:
- Python
- TypeScript
Start the terminal interface
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:Start Remote Control
Use Claude subscription sign-in for this interface. If you previously used an API key in this sandbox, remove it from the shell and any Claude settings before signing in:tmux session in your project:
tmux, start Claude:
/exit, then start the Remote Control server in the same directory:
--spawn same-dir option uses the project directory for remote sessions. If prompted, accept the first-use confirmation. Open the displayed Claude Code URL in a browser signed in to the same Claude account.
After the connection works, detach from tmux with Ctrl-b, then d, and exit the sandbox shell. The tmux session keeps the server running. To return, rerun the attachment script and run tmux attach -t claude-remote.
Check the session
For the terminal interface, send the prompt in the attached Claude Code TUI. For Remote Control, open the session at claude.ai/code in your browser, or in the Claude mobile or Desktop app, using the same account. Choose a unique, non-secret test value and replace[PROOF-VALUE] in this prompt:
/exit and, for the SDK setup, exit the sandbox shell with exit. From your local terminal, verify the result using the command for your setup:
- cws-agent
- Sandbox SDK
Return to a running sandbox
Exiting Claude or closing your terminal leaves the sandbox running. To return from another terminal or machine, install the same client and authenticate with credentials that can access the sandbox. Forcws-agent, find the session by name and open a new Claude terminal:
connect command uses the existing sandbox and files. It doesn’t resume a previous conversation. To continue a saved conversation, first exit its original Claude process. Then list the history and replace [CONVERSATION-ID] with the ID to resume:
tmux or the cws-agent worktree sessions.
Reconnecting doesn’t reset the sandbox’s lifetime. If the sandbox has stopped, restore a saved workspace instead.
Keep results and stop
Save progress during a long session instead of waiting until the lifetime is nearly over. Withcws-agent, wait for Claude to finish writing and pause other workspace writers, then capture the /workspace directory without stopping the sandbox:
READY snapshot. A snapshot captures files at that point in time. Later edits need another snapshot. For capture behavior and saved credentials, see the snapshot guidance. Don’t rely on lifetime expiry to save your latest changes.
In your local terminal, copy the verified text result to your machine:
down command confirms a snapshot before stopping. If snapshot creation fails, it leaves the sandbox running. Check cws-agent status [SANDBOX-NAME] and resolve the failure before retrying. To stop without saving current changes, use cws-agent down [SANDBOX-NAME] --no-snapshot.
SDK を直接使用する場合、この例では永続マウントを使用しません。ワークスペースを復元できるようにするには、作成時にファイルシステムスナップショットを設定してください。ファイル操作で結果を取り出してから、サンドボックスを停止してください。
- Python
- TypeScript
cws-agent, restore it into a new sandbox. If the skills/MCP import prompt appears, press Enter to skip it:
/exit, then repeat the sign-in and server startup steps, starting with cws-agent connect. Skip the launch command because restore has already created the sandbox. For saved conversations and parallel worktrees, see the cws-agent sessions guide.
Troubleshoot
Use these checks to resolve common issues:- サンドボックスの作成に失敗する場合は、W&B APIキーと認証設定を確認してください。
- インストール、クローン、またはモデルへのリクエストが失敗する場合は、アウトバウンドの接続性と、該当するプロバイダーの認証情報を確認してください。
- ターミナルが切断された場合は、サンドボックスの実行中であれば再度アタッチできます。ターミナルが切断されてもプロセスを維持したい場合は、
tmuxなどのターミナルマルチプレクサ内で実行してください。 - Remote Control で認証が拒否される場合は、Claude のサブスクリプションでサインインしてください。また、リモート環境または Claude の設定から、競合する APIキーの認証情報を削除してください。
- Remote Control を利用できない場合は、Anthropic のトラブルシューティングガイドを参照し、組織設定、カスタム API エンドポイント、および必須の機能チェックを無効にする環境変数を確認してください。
- サンドボックスの有効期限が切れた場合は、新しいサンドボックスを作成してください。有効期間は作成後に延長できません。また、この SDK の例ではファイルシステムが自動保存されない点に注意してください。
Data handling
Commands execute in the sandbox, while model requests go to your configured provider. Remote Control sends prompts, tool activity, and conversation content to Anthropic and stores a transcript to synchronize connected devices. See Remote Control security and Claude Code data usage.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.