> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandboxes에서 에이전트 실행하기

> CoreWeave에서 장시간 세션, 병렬 작업, 도구를 활용해 대화형 에이전트와 자율 에이전트를 실행하세요.

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.

스크린샷, 마우스 입력, 키보드 입력으로 그래픽 데스크톱을 조작하는 에이전트는 [샌드박스에서 컴퓨터 사용 에이전트 실행하기](/products/sandboxes/serverless/tutorials/computer-use)를 참조하세요.

## 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](agents/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](agents/cursor) | The sandbox | An attached terminal or a script | Edit a repository interactively or run unattended coding tasks. |
| [OpenCode CLI](agents/opencode) | The sandbox | An attached terminal or a command | Run coding tasks with W\&B Serverless Inference or another model provider. |
| [Muse Code](agents/muse-code) | The sandbox | The Sandbox SDK | Run a CLI task on a repository and retrieve the result. |
| [Pi](agents/pi) | The sandbox | An attached terminal | Work on a repository with your choice of model provider, including W\&B Serverless Inference. |
| [Claude Managed Agents](agents/claude-managed-agents) | Anthropic's managed service | The Managed Agents API | Connect a self-hosted worker to a managed agent session. |
| [Codex](agents/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](agents/devin-outposts) | Devin Cloud | Devin Cloud | Run Devin's commands in a sandbox through an outpost worker. |
| [OpenAI Agents API](agents/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](/products/sandboxes/client) to create an environment, execute tool calls, collect results, and stop compute from your own harness. Start with [command execution](client/guides/execution), [file operations](client/guides/file-operations), and [cleanup patterns](client/guides/cleanup-patterns).

## Get started with cws-agent

[`cws-agent`](https://github.com/coreweave/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.

[설치 안내](https://github.com/coreweave/cws-agent#install)에 따라 설치한 후 인테그레이션 가이드를 선택하세요. 해당 가이드의 `cws-agent` 예시에서는 샌드박스에 액세스할 때 [W\&B API 키](https://forge.coreweave.com/settings#apikeys)를 사용합니다. 에이전트 공급자 인증은 별도로 진행하세요.

```bash theme={"system"}
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](/ko/products/sandboxes/serverless/agents/openai-agents-api) 레시피는 기본적으로 `CWSANDBOX_API_KEY`가 필요하며, `--sandbox-auth wandb`를 전달할 때만 W\&B 키를 선택합니다. 따라서 이 변수의 설정을 해제하면 기본 run이 실패합니다.

For configuration imports, parallel sessions, and saving or restoring workspaces, see the [`cws-agent` documentation](https://github.com/coreweave/cws-agent#more). 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 설치 및 인증](/ko/products/sandboxes/serverless/get-started#run-your-first-sandbox)을 완료한 후 다음 생성 요청을 사용하여 수명이 24시간인 샌드박스를 생성하세요. Python 클라이언트에는 `wandb` extra가 필요하며, TypeScript에서는 W\&B 클라이언트 진입점을 사용합니다.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    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}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"system"}
    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}`);
    ```
  </Tab>
</Tabs>

Save the printed ID to [reconnect with the SDK](client/guides/sandbox-lifecycle#reconnection). 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:

```bash theme={"system"}
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](https://github.com/tmux/tmux/wiki/Getting-Started) 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](client/guides/execution#set-a-timeout) and [sandbox lifecycle](client/guides/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:

```text theme={"system"}
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:

```markdown title=".claude/agents/test-reader.md" theme={"system"}
---
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](https://code.claude.com/docs/en/sub-agents).

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](https://github.com/coreweave/cws-agent/blob/main/docs/sessions.md) 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](client/guides/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:

  ```bash theme={"system"}
  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](https://github.com/coreweave/cws-agent/blob/main/docs/config-import.md).
* **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](client/guides/execution#sequential-compared-with-parallel-execution) 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.

중지하기 전에 결과를 복사해 두거나, 변경 사항을 저장소에 푸시하거나, [파일 시스템 스냅샷](/products/sandboxes/serverless/file-system-snapshots)을 사용할 수 있도록 스냅샷 볼륨을 설정하세요. 스냅샷은 파일만 보존하며 실행 중인 프로세스는 보존하지 않습니다. 공급자의 대화 이력은 별도의 라이프사이클을 따릅니다.