> ## 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.

# Claude Code

> CoreWeave 샌드박스에서 Claude Code를 실행하고 터미널, Claude 앱 또는 claude.ai에서 상호작용하세요.

CoreWeave 샌드박스에서 Claude Code를 실행하고 상호작용 방식을 선택하세요. 터미널 사용자 인터페이스(TUI)를 사용하면 로컬 터미널에서 샌드박스 내부의 Claude Code를 제어할 수 있습니다. Remote Control을 사용하면 Claude 모바일 앱, Claude Desktop 또는 [claude.ai/code](https://claude.ai/code)에서 상호작용할 수 있습니다. 어느 방식이든 에이전트 프로세스, 도구, 워크스페이스는 모두 샌드박스에서 실행되며, 모델 요청은 설정한 모델 공급자로 전송됩니다.

| 인터페이스 | 상호작용 위치 | Claude 인증 |
| - | - | - |
| 터미널(TUI) | 샌드박스에 연결된 로컬 터미널 | Claude 계정 또는 지원되는 API 사용자 인증 정보 |
| Remote Control | Claude 모바일 앱, Claude Desktop 또는 claude.ai/code | `/login`으로 로그인한 Claude 구독 계정 |

Anthropic이 에이전트 루프를 관리하고 샌드박스에서 도구를 실행하는 인테그레이션은 [Claude Managed Agents](/ko/products/sandboxes/agents/claude-managed-agents)를 참조하세요.

<h2 id="prerequisites">
  사전 요구 사항
</h2>

시작하기 전에 다음이 필요합니다.

* `SANDBOX_USER` 액션이 부여된 [CoreWeave API 액세스 토큰](/ko/products/sandboxes/placement#choose-and-get-credentials)
* 터미널 인터페이스를 사용하려면 Claude 계정 또는 Claude Code에서 지원하는 API 사용자 인증 정보가 필요합니다. Remote Control을 사용하려면 Claude Pro, Max, Team 또는 Enterprise 구독이 필요합니다. API 키와 `claude setup-token` 토큰으로는 Remote Control을 인증할 수 없습니다.
* 샌드박스에서 복제할 수 있는 저장소 URL. 예시에서는 공개 저장소를 사용합니다. 비공개 저장소를 사용하려면 샌드박스 내부에 Git 사용자 인증 정보가 있어야 합니다.

이 가이드를 진행할 터미널에서 CoreWeave API 액세스 토큰을 내보내세요.

```bash theme={"system"}
export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"
```

Remote Control을 사용하려면 Team 및 Enterprise 계정에서는 Owner가 이 기능을 활성화해야 합니다. 또한 조직에서 이 기능의 전사본 저장을 허용해야 합니다. Zero Data Retention 요구 사항이 적용되는 조직에서는 이 기능을 활성화할 수 없습니다. Anthropic의 [Remote Control 요구 사항](https://code.claude.com/docs/en/remote-control#requirements)을 확인하세요.

연결에는 아웃바운드 HTTPS가 사용되므로 공개 샌드박스 엔드포인트나 인바운드 포트가 필요하지 않습니다.

두 설정 방식 모두 하루 근무 시간에 맞춰 샌드박스 수명을 8시간으로 설정합니다. 수명은 생성 시점부터 계산되며 설정 시간과 유휴 시간도 포함되고, 연장할 수 없습니다. 수명이 만료되면 Claude가 작업 중이더라도 샌드박스가 중지되고 세션이 종료됩니다. 작업을 마치면 수명이 만료되기 전에 [결과를 저장하고 샌드박스를 중지](#keep-results-and-stop)하세요.

밤새 작업하려면 생성 시 24시간을 선택하세요. `cws-agent`에서는 `--lifetime 24h`를 사용하세요. 소프트웨어 개발 키트(SDK) 예시에서는 Python의 `max_lifetime_seconds` 또는 TypeScript의 `maxLifetimeSeconds`를 `24 * 3600`으로 설정하세요.

<h2 id="quick-start-with-cws-agent">
  cws-agent 빠른 시작
</h2>

`cws-agent`로 샌드박스를 생성하려면 이 설정 방법을 선택하세요. 클라이언트 라이브러리로 직접 생성하려면 [Sandboxes SDK로 설정](#set-up-with-the-sandbox-sdk)으로 건너뛰세요. 두 방법 모두 어느 인터페이스든 사용할 수 있습니다.

[`cws-agent` 설치 안내](https://github.com/coreweave/cws-agent#install)를 따르세요. 이 도구는 [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots#start-a-sandbox-with-a-snapshot-mount)으로 워크스페이스를 저장하고 복원할 수 있도록 스냅샷 볼륨을 설정합니다.

Claude가 열리기 전에 `cws-agent`가 임포트할 로컬 스킬과 Model Context Protocol(MCP) 서버의 미리 보기를 표시할 수 있습니다. 이 가이드에서는 임포트 프롬프트에서 **Enter**를 눌러 건너뛰세요. 임포트는 나중에 [에이전트 도구 가이드](/ko/products/sandboxes/agents#use-tools-efficiently)를 참고하여 설정할 수 있습니다.

다음 인터페이스 중 하나를 선택하세요. `[SANDBOX-NAME]`을 `cws-agent` 세션 이름으로, `[REPOSITORY-URL]`을 공개 저장소 URL로 바꾸세요. 세션 이름은 소문자, 숫자 또는 하이픈으로 구성된 1\~40자로 지정하고, 문자 또는 숫자로 시작해야 합니다.

<h3 id="use-the-terminal-interface">
  터미널 인터페이스 사용
</h3>

Anthropic API 키를 사용하려면 샌드박스를 시작하거나 복원하기 전에 로컬 터미널에서 `ANTHROPIC_API_KEY`에 키를 설정하세요. `cws-agent`는 이 변수를 샌드박스에 전달합니다. API 키 인증에는 브라우저 로그인이 필요하지 않습니다. [Claude Code 인증](https://code.claude.com/docs/en/authentication)을 참조하세요.

Claude Code를 시작하고 로컬 터미널을 연결하세요:

```bash theme={"system"}
cws-agent launch [SANDBOX-NAME] --repo-url [REPOSITORY-URL] --lifetime 8h --permission-mode native
```

Claude Code가 샌드박스의 프로젝트 디렉터리에서 열립니다. 워크스페이스 신뢰 프롬프트가 표시되면 안내를 따르세요. API 키 인증을 사용하는 경우 메시지가 표시되면 키를 승인하세요. 계정 인증이 필요한 경우 Claude를 종료하고 `cws-agent login [SANDBOX-NAME]`을 실행한 다음, 해당 환경에서 `/login`을 완료하세요.

`--permission-mode native` 옵션은 Claude 자체 승인 설정을 사용합니다. 이 옵션이 없으면 `cws-agent`는 기본적으로 해당 승인 메시지를 건너뜁니다. [권한 모드](https://github.com/coreweave/cws-agent/blob/main/docs/permissions.md)를 참조하세요.

API 키가 설정되어 있는데도 Claude가 `Not logged in`을 표시하고 키 승인 메시지를 표시하지 않는 경우, `/exit`로 종료한 다음 온보딩을 활성화하여 다시 연결하세요:

```bash theme={"system"}
cws-agent connect [SANDBOX-NAME] --cmd 'unset IS_DEMO; exec claude'
```

이 명령은 Claude 자체 승인 설정을 사용합니다. 계속하기 전에 워크스페이스 신뢰 및 API 키 확인 요청을 수락하세요.

[세션 확인](#check-the-session)으로 이동하여 프롬프트를 보내고 결과를 확인하세요.

<h3 id="use-remote-control">
  Remote Control 사용
</h3>

분리된 샌드박스를 생성한 다음, 터미널을 연결하여 구독 계정으로 로그인하세요.

```bash theme={"system"}
cws-agent launch [SANDBOX-NAME] --repo-url [REPOSITORY-URL] --lifetime 8h --detach
cws-agent connect [SANDBOX-NAME] --cmd 'unset IS_DEMO CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_API_KEY; exec claude'
```

연결 명령어는 구독 로그인이나 Remote Control 기능 확인을 방해할 수 있는 설정을 지웁니다. 또한 온보딩을 활성화하기 위해 `IS_DEMO` 설정을 해제합니다. [Claude Code 환경 변수](https://code.claude.com/docs/en/env-vars)를 참조하세요.

Claude에서 Claude 구독 계정으로 `/login`을 완료하고 프로젝트 신뢰 프롬프트를 수락하세요. `/remote-control`을 실행하고 최초 사용 확인을 수락한 다음 `/exit`로 Claude를 종료하세요. 분리된 서버를 시작하기 전에 확인 질문에 응답해야 하므로 이 단계는 대화형으로 진행하세요.

로컬 터미널에서 Claude 자체 승인 설정을 사용해 Remote Control을 시작하세요.

```bash theme={"system"}
cws-agent rc [SANDBOX-NAME] --permission-mode native
```

세션 URL이 표시되면 해당 URL을 여세요. 프로세스가 시작되었다는 메시지만으로는 연결되었다고 판단할 수 없습니다. 웹, 모바일 또는 데스크톱 클라이언트에서 프롬프트를 보낸 후 [세션 확인](#check-the-session)에 설명된 방법으로 결과를 확인하세요.

URL이 표시되지 않으면 원격 로그를 살펴보세요.

```bash theme={"system"}
cws-agent exec [SANDBOX-NAME] 'cat /workspace/home/remote-control.log'
```

재시도하기 전에 로그인 또는 자격 요건 오류를 먼저 해결하세요. 서버가 대화형 프롬프트 입력을 기다리고 있다면, 같은 샌드박스에서 연결된(attached) `tmux` 세션으로 서버를 다시 시작하세요. `cws-agent rc` 명령어는 출력을 로그로 리디렉션하므로, 기존 세션에 연결해도 프롬프트가 표시되지 않습니다.

로컬 터미널에서 대기 중인 서버를 중지하고 새 세션을 여세요.

```bash theme={"system"}
cws-agent exec [SANDBOX-NAME] 'tmux kill-session -t cws-remote-control'
cws-agent connect [SANDBOX-NAME] --cmd 'tmux new-session -s cws-remote-control'
```

`tmux` 안에서 Remote Control을 시작해 세션이 프로젝트 디렉터리를 사용하도록 하세요:

```bash theme={"system"}
unset IS_DEMO CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_API_KEY
cd /workspace/project
claude remote-control --spawn same-dir
```

표시되는 프롬프트에 응답한 뒤 화면에 나타난 Claude Code URL을 여세요. 연결이 정상적으로 작동하면 **Ctrl-b**를 누른 다음 **d**를 눌러 세션에서 분리하세요. 그러면 서버는 계속 실행됩니다. 대체 세션은 로그를 업데이트하지 않고 `tmux`에 출력을 표시합니다. 세션으로 다시 돌아가려면 `cws-agent connect [SANDBOX-NAME] --cmd 'tmux attach -t cws-remote-control'`을 실행하세요.

<h2 id="set-up-with-the-sandbox-sdk">
  Sandboxes SDK로 설정
</h2>

Sandboxes SDK로 샌드박스를 생성하는 대체 방법으로, 두 인터페이스 모두에 사용할 수 있습니다. 이 방법은 `cws-agent`에 의존하지 않으며 스냅샷을 설정하지 않습니다.

이 가이드에서 생성한 가상 환경에서 Python 코드 조각을 실행하세요. TypeScript 코드 조각은 클라이언트를 설치한 프로젝트에 `.mts` 파일로 저장한 다음, `npx tsx [FILENAME].mts`로 실행하세요.

<h3 id="create-the-sandbox">
  샌드박스 생성
</h3>

클라이언트를 선택하고 로컬에 설치하세요.

<Tabs>
  <Tab title="Python">
    Python 3.11 이상과 `uv`를 사용하세요.

    ```bash theme={"system"}
    uv venv --python 3.11
    source .venv/bin/activate
    uv pip install 'cwsandbox>=1.14.2'
    ```
  </Tab>

  <Tab title="TypeScript">
    Node.js 22 이상을 사용하세요. 프로젝트에 클라이언트와 TypeScript 러너를 설치하세요.

    ```bash theme={"system"}
    npm install @coreweave/cwsandbox@0.5.0-beta.0 tsx
    ```
  </Tab>
</Tabs>

사용하는 언어에 맞는 스크립트를 표시된 파일 이름으로 저장하세요. 이 스크립트는 Claude Code와 `tmux`를 설치한 다음, 명령줄 인수로 전달한 저장소를 복제합니다.

두 스크립트 모두 `apt-get`으로 패키지를 설치하고 `/root/.local/bin/claude`를 사용하므로 컨테이너가 root로 실행되어야 합니다. 러너의 정책에서 이 사용자를 허용해야 합니다.

<Tabs>
  <Tab title="Python">
    ```python title="create_claude_sandbox.py" theme={"system"}
    import sys

    from cwsandbox import Sandbox

    bootstrap = """
    set -o pipefail
    apt-get update -qq
    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq tmux >/dev/null
    curl -fsSL https://claude.ai/install.sh | bash
    mkdir -p /workspace
    """

    sandbox = Sandbox.run(
        container_image="node:22-bookworm",
        resources={"cpu": "2", "memory": "4Gi"},
        max_lifetime_seconds=8 * 3600,
        tags=["claude-code"],
    )
    try:
        sandbox.wait()
        commands = [
            ["bash", "-ec", bootstrap],
            ["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}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript title="create_claude_sandbox.mts" theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

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

    const bootstrap = `
    set -o pipefail
    apt-get update -qq
    DEBIAN_FRONTEND=noninteractive apt-get install -y -qq tmux >/dev/null
    curl -fsSL https://claude.ai/install.sh | bash
    mkdir -p /workspace
    `;

    const client = createSandboxClientFromEnv();
    const sandbox = await client.create({
      containerImage: "node:22-bookworm",
      resources: { cpu: "2", memory: "4Gi" },
      maxLifetimeSeconds: 8 * 3600,
      waitUntilRunning: false,
      tags: ["claude-code"],
    });
    try {
      await sandbox.wait();
      const commands = [
        ["bash", "-ec", bootstrap],
        ["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}`);
    ```
  </Tab>
</Tabs>

`[REPOSITORY-URL]`을 공개 저장소 URL로 바꾸세요.

<Tabs>
  <Tab title="Python">
    ```bash theme={"system"}
    python create_claude_sandbox.py [REPOSITORY-URL]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={"system"}
    npx tsx create_claude_sandbox.mts [REPOSITORY-URL]
    ```
  </Tab>
</Tabs>

출력된 샌드박스 ID를 기록해 두세요. 이 독립 실행형 예시에서는 스크립트가 종료된 후에도 샌드박스가 계속 실행됩니다. 샌드박스는 직접 중지하거나 8시간 수명이 만료될 때까지 실행됩니다. Python에서는 샌드박스를 `Session` 또는 컨텍스트 관리자로 래핑하면 이러한 정리 작업 동작이 달라집니다.

<h3 id="attach-your-terminal">
  터미널 연결하기
</h3>

SDK를 사용하여 동일한 CoreWeave 사용자 인증 정보로 로컬 터미널을 연결하세요. 이 스크립트는 키 입력을 샌드박스 셸로 전달하고, 셸이 종료되면 터미널을 원래 상태로 복원합니다.

<Tabs>
  <Tab title="Python">
    macOS 또는 Linux에서 다음 내용을 `attach_sandbox.py`로 저장하세요.

    ```python title="attach_sandbox.py" theme={"system"}
    import os
    import shutil
    import sys
    import termios
    import threading
    import tty

    from cwsandbox import 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]).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)
    ```
  </Tab>

  <Tab title="TypeScript">
    다음 내용을 `attach_sandbox.mts`로 저장하세요.

    ```typescript title="attach_sandbox.mts" theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

    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 || 80,
      rows: process.stdout.rows || 24,
    });
    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();
    }
    ```
  </Tab>
</Tabs>

`[SANDBOX-ID]`를 출력된 ID로 바꾼 다음 실행하세요.

<Tabs>
  <Tab title="Python">
    ```bash theme={"system"}
    python attach_sandbox.py [SANDBOX-ID]
    ```
  </Tab>

  <Tab title="TypeScript">
    ```bash theme={"system"}
    npx tsx attach_sandbox.mts [SANDBOX-ID]
    ```
  </Tab>
</Tabs>

`cwsandbox sh [SANDBOX-ID]` 단축 명령을 선택적으로 사용할 수 있습니다. `cli` extra를 설치하고, `CWSANDBOX_API_KEY`에는 해당 샌드박스에 사용한 CoreWeave API 액세스 토큰을 계속 설정해 두세요.

이제 터미널이 샌드박스 내부의 셸에 연결되었습니다. 다음 인터페이스 중 하나를 선택하여 Claude Code를 시작하세요.

<h3 id="start-the-terminal-interface">
  터미널 인터페이스 시작
</h3>

API 키 인증을 사용하는 경우 Claude를 시작하기 전에 샌드박스의 Bash 셸에서 키를 입력하세요. 입력 내용은 화면에 표시되지 않으며 명령 이력에도 남지 않습니다.

```bash theme={"system"}
read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
printf '\n'
```

샌드박스 내에서 복제한 저장소에서 Claude를 시작하세요:

```bash theme={"system"}
cd /workspace/project
/root/.local/bin/claude
```

API 키를 사용하는 경우, 이를 승인하세요. 그렇지 않으면 계정 로그인을 완료하세요. 그런 다음 워크스페이스 신뢰 프롬프트를 수락하고 [세션 확인](#check-the-session)으로 이동하세요.

<h3 id="start-remote-control">
  Remote Control 시작
</h3>

이 인터페이스에서는 Claude 구독 계정으로 로그인하세요. 이전에 이 샌드박스에서 API 키를 사용했다면 로그인하기 전에 셸과 모든 Claude 설정에서 해당 키를 제거하세요:

```bash theme={"system"}
unset ANTHROPIC_API_KEY CLAUDE_CODE_OAUTH_TOKEN
```

샌드박스 안의 프로젝트에서 이름을 지정한 `tmux` 세션을 여세요.

```bash theme={"system"}
cd /workspace/project
tmux new-session -s claude-remote
```

`tmux`에서 Claude를 실행하세요.

```bash theme={"system"}
/root/.local/bin/claude
```

구독 계정으로 로그인을 완료하고 워크스페이스 신뢰 프롬프트를 수락하세요. `/exit`로 Claude를 종료한 후 같은 디렉터리에서 Remote Control 서버를 시작하세요.

```bash theme={"system"}
/root/.local/bin/claude remote-control --name "CoreWeave sandbox" --spawn same-dir
```

`--spawn same-dir` 옵션을 지정하면 원격 세션에서 프로젝트 디렉터리를 사용합니다. 확인 메시지가 표시되면 최초 사용 확인을 수락하세요. 표시된 Claude Code URL을 같은 Claude 계정으로 로그인한 브라우저에서 여세요.

연결이 확인되면 **Ctrl-b**를 누른 다음 **d**를 눌러 `tmux`에서 분리하고 샌드박스 셸을 종료하세요. 서버는 `tmux` 세션에서 계속 실행됩니다. 다시 접속하려면 연결 스크립트를 다시 실행한 다음 `tmux attach -t claude-remote`를 실행하세요.

<h2 id="check-the-session">
  세션 확인
</h2>

터미널 인터페이스를 사용하는 경우 연결된 Claude Code TUI에서 프롬프트를 보내세요. Remote Control을 사용하는 경우 동일한 계정으로 브라우저에서 claude.ai/code 에 접속하거나 Claude 모바일 앱 또는 Desktop 앱에서 세션을 여세요.

다른 값과 겹치지 않으면서 민감하지 않은 테스트 값을 정한 다음, 다음 프롬프트의 `[PROOF-VALUE]`를 해당 값으로 바꾸세요.

```text theme={"system"}
/workspace/project/sandbox-proof.txt 파일에 [PROOF-VALUE] 텍스트를 그대로 기록한 다음, 다시 읽어 와 주세요.
```

승인을 요청하면 파일 쓰기를 승인하세요. 터미널 인터페이스를 사용한 경우 `/exit`로 Claude를 종료하고, SDK 설정을 사용한 경우 `exit`로 샌드박스 셸도 종료하세요. 그런 다음 로컬 터미널에서 사용 중인 설정에 맞는 명령어로 결과를 확인하세요.

<Tabs>
  <Tab title="cws-agent">
    ```bash theme={"system"}
    cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt'
    ```
  </Tab>

  <Tab title="Sandboxes SDK">
    <Tabs>
      <Tab title="Python">
        ```python theme={"system"}
        from cwsandbox import Sandbox

        sandbox = Sandbox.from_id("[SANDBOX-ID]").result()
        result = sandbox.exec(["cat", "/workspace/project/sandbox-proof.txt"], check=True).result()
        print(result.stdout, end="")
        ```
      </Tab>

      <Tab title="TypeScript">
        ```typescript theme={"system"}
        import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

        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);
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

값이 일치하면 직접 생성한 샌드박스에 Claude가 파일을 썼음을 확인할 수 있습니다.

<h2 id="return-to-a-running-sandbox">
  실행 중인 샌드박스로 돌아가기
</h2>

Claude를 종료하거나 터미널을 닫아도 샌드박스는 계속 실행됩니다. 다른 터미널이나 머신에서 다시 접속하려면 동일한 클라이언트를 설치한 후, 해당 샌드박스에 액세스할 수 있는 사용자 인증 정보로 인증하세요.

`cws-agent`를 사용하는 경우 이름으로 세션을 찾은 다음 새 Claude 터미널을 여세요.

```bash theme={"system"}
cws-agent list
cws-agent status [SANDBOX-NAME]
cws-agent connect [SANDBOX-NAME] --permission-mode native
```

`connect` 명령어는 기존 샌드박스와 파일을 그대로 사용하지만, 이전 대화를 재개하지는 않습니다. 저장된 대화를 이어서 진행하려면 먼저 해당 대화를 실행한 원본 Claude 프로세스를 종료하세요. 그런 다음 이력 목록을 확인하고 `[CONVERSATION-ID]`를 재개할 ID로 바꾸세요:

```bash theme={"system"}
cws-agent session history [SANDBOX-NAME]
cws-agent session resume [SANDBOX-NAME] [CONVERSATION-ID] --permission-mode native
```

SDK 방식을 사용하는 경우 동일한 샌드박스 ID로 [터미널 연결 스크립트](#attach-your-terminal)를 다시 실행한 다음 Claude를 다시 시작하세요. 샌드박스의 수명이 더 길더라도 SDK 셸 세션 하나는 24시간이 지나면 종료됩니다. 샌드박스는 계속 실행 중이므로 스크립트를 다시 실행하면 재연결할 수 있습니다. Remote Control을 사용하는 경우 해당 서버가 실행 중인 동안 세션 URL을 다시 여세요.

샌드박스 연결과 에이전트 프로세스의 수명은 서로 별개입니다. 연결을 끊은 후에도 터미널 에이전트가 계속 작업해야 한다면 `tmux` 또는 `cws-agent` 워크트리 세션을 사용하세요.

재연결해도 샌드박스의 수명은 재설정되지 않습니다. 샌드박스가 이미 중단되었다면 저장된 워크스페이스를 복원하세요.

<h2 id="keep-results-and-stop">
  결과 보존 및 중지
</h2>

수명이 거의 끝날 때까지 기다리지 말고, 긴 세션 중간중간 진행 상황을 저장하세요. `cws-agent`를 사용하는 경우 Claude가 쓰기를 마칠 때까지 기다리고 워크스페이스에 쓰는 다른 프로세스를 일시 중지한 다음, 샌드박스를 중지하지 않은 상태로 `/workspace` 디렉터리를 캡처하세요.

```bash theme={"system"}
cws-agent snapshot [SANDBOX-NAME]
```

명령어 출력에 `READY` 상태의 스냅샷이 표시될 때까지 기다리세요. 스냅샷은 생성 시점의 파일을 캡처합니다. 이후에 편집한 내용을 보존하려면 스냅샷을 다시 생성해야 합니다. 캡처 동작과 저장된 사용자 인증 정보에 대한 자세한 내용은 [스냅샷 가이드](https://github.com/coreweave/cws-agent/blob/main/docs/usage.md#snapshots)를 참조하세요. 수명 만료 시 최신 변경 사항이 자동으로 저장된다고 가정하지 마세요.

로컬 터미널에서 검증된 텍스트 결과를 로컬 컴퓨터로 복사하세요.

```bash theme={"system"}
cws-agent exec [SANDBOX-NAME] 'cat /workspace/project/sandbox-proof.txt' > sandbox-proof.txt
```

코드 변경 사항은 [변경 사항 가져오기](https://github.com/coreweave/cws-agent/blob/main/docs/usage.md#get-changes-back)를 참조하세요. 스냅샷은 원격 워크스페이스를 보존할 뿐, 파일을 로컬 머신으로 복사하지는 않습니다.

작업을 마쳤다면 진행 중인 작업과 워크스페이스 쓰기가 모두 완료될 때까지 기다린 다음, 워크스페이스를 저장하고 컴퓨팅을 중지하세요.

```bash theme={"system"}
cws-agent down [SANDBOX-NAME]
```

`down` 명령어는 샌드박스를 중지하기 전에 스냅샷이 생성되었는지 확인합니다. 스냅샷 생성에 실패하면 샌드박스는 계속 실행 상태로 유지됩니다. `cws-agent status [SANDBOX-NAME]`을 확인하고 실패 원인을 해결한 후 다시 시도하세요. 현재 변경 사항을 저장하지 않고 중지하려면 `cws-agent down [SANDBOX-NAME] --no-snapshot`을 사용하세요.

SDK를 직접 사용하는 경우 이 예제에는 영구 마운트가 없습니다. 복원 가능한 워크스페이스가 필요하면 샌드박스를 생성할 때 [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots)을 설정하세요. [파일 작업](/ko/products/sandboxes/client/guides/file-operations)으로 결과를 외부로 복사한 다음 샌드박스를 중지하세요.

<Tabs>
  <Tab title="Python">
    ```python theme={"system"}
    from cwsandbox import Sandbox

    sandbox = Sandbox.from_id("[SANDBOX-ID]").result()
    sandbox.stop().result()
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"system"}
    import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

    const client = createSandboxClientFromEnv();
    const sandbox = await client.fromId("[SANDBOX-ID]");
    await sandbox.stop();
    ```
  </Tab>
</Tabs>

Claude만 종료해서는 샌드박스가 중지되지 않습니다. 샌드박스를 중지하면 Remote Control을 포함한 에이전트 프로세스가 모두 종료됩니다. 스냅샷에서 파일을 복원해도 이 프로세스는 복원되지 않으므로, 필요하면 로그인한 후 Remote Control을 다시 시작하세요.

`cws-agent`로 저장한 워크스페이스로 돌아가려면 새 샌드박스에 복원하세요. 스킬/MCP 임포트 프롬프트가 나타나면 **Enter**를 눌러 건너뛰세요.

```bash theme={"system"}
cws-agent restore [SANDBOX-NAME] --lifetime 8h --connect --permission-mode native
```

Remote Control을 사용하는 경우 `/exit`로 복원된 Claude TUI를 종료한 다음, `cws-agent connect`부터 [로그인 및 서버 시작 단계](#use-remote-control)를 다시 진행하세요. 복원 과정에서 이미 샌드박스가 생성되었으므로 실행 명령어는 건너뛰세요. 저장된 대화와 병렬 워크트리에 대한 자세한 내용은 [`cws-agent` 세션 가이드](https://github.com/coreweave/cws-agent/blob/main/docs/sessions.md)를 참조하세요.

<h2 id="troubleshoot">
  문제 해결
</h2>

다음 항목을 확인하여 일반적인 문제를 해결하세요.

* 샌드박스 생성에 실패하면 CoreWeave API 액세스 토큰과 인증 설정을 확인하세요.
* 설치, 복제 또는 모델 요청이 실패하면 아웃바운드 연결 상태와 해당 공급자의 사용자 인증 정보를 확인하세요. [CoreWeave Kubernetes Service (CKS) 배치](/ko/products/sandboxes/get-started-cks)를 사용하는 경우 러너의 정책에서 해당 대상을 허용해야 합니다.
* 터미널 연결이 끊어지면 샌드박스가 실행 중일 때 다시 연결하세요. 터미널 연결이 끊어져도 프로세스가 유지되게 하려면 `tmux` 같은 터미널 멀티플렉서에서 프로세스를 실행하세요.
* Remote Control에서 인증이 거부되면 Claude 구독 계정으로 로그인하세요. 원격 환경이나 Claude 설정에 충돌하는 API 키 사용자 인증 정보가 있다면 제거하세요.
* Remote Control을 사용할 수 없으면 [Anthropic의 문제 해결 가이드](https://code.claude.com/docs/en/remote-control#troubleshooting)에서 조직 설정, 맞춤형 API 엔드포인트, 필수 기능 확인을 비활성화하는 환경 변수 관련 내용을 확인하세요.
* 샌드박스가 만료되면 새로 만드세요. 수명은 생성 후에 연장할 수 없으며, 이 SDK 예시는 파일 시스템을 자동으로 저장하지 않습니다.

<h2 id="data-handling">
  데이터 처리
</h2>

명령어는 샌드박스에서 실행되고, 모델 요청은 설정한 공급자로 전송됩니다. Remote Control은 프롬프트, 도구 활동, 대화 내용을 Anthropic으로 전송하며, 연결된 기기 간 동기화를 위해 전사본을 저장합니다. 자세한 내용은 [Remote Control 보안](https://code.claude.com/docs/en/remote-control#connection-and-security) 및 [Claude Code 데이터 사용](https://code.claude.com/docs/en/data-usage)을 참조하세요.

<h2 id="next-steps">
  다음 단계
</h2>

자세한 내용은 다음 가이드를 참조하세요:

* [대화형 셸 및 TTY](/ko/products/sandboxes/client/guides/interactive-shells)에서는 SDK에서 터미널 액세스를 다룹니다.
* [샌드박스 라이프사이클](/ko/products/sandboxes/client/guides/sandbox-lifecycle)에서는 대기, 재연결, 중지를 다룹니다.
* [Claude Code 문서](https://code.claude.com/docs/en/overview)에서는 에이전트 설정 및 인증을 다룹니다.

claude.ai/code 에서 새 클라우드 세션을 시작할 때마다 워커 샌드박스를 프로비저닝하려면 [Claude Code 클라우드 세션](/ko/products/sandboxes/agents/claude-code-cloud)을 참조하세요.