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 토큰을 모두 unset하세요:
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을 사용할 수 없는 경우, 조직 설정, 맞춤형 API 엔드포인트, 필수 기능 확인을 비활성화하는 환경 변수와 관련된 내용은 Anthropic 문제 해결 가이드를 참고하세요.
- 샌드박스가 만료되면 새로 생성하세요. 수명은 생성 후에는 연장할 수 없으며, 이 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.