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

# 샌드박스에서 Pi 실행하기

> 연결된 터미널에서 Pi를 실행하고(Serverless Inference는 선택 사항), 작업 결과를 가져오세요.

CoreWeave 샌드박스 안에서 [Pi](https://github.com/earendil-works/pi)를 실행하면 터미널에서 저장소 작업을 할 수 있습니다. Pi의 에이전트 프로세스, 파일, 셸 명령어는 모두 샌드박스에서 실행되며, 모델 요청은 선택한 공급자로 전송됩니다. 이 가이드에서는 워크스페이스를 생성하고, Pi에 연결하고, 작업 결과를 확인하고, 컴퓨팅을 중지하는 방법을 다룹니다.

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

시작하기 전에 다음 항목을 준비하세요.

* macOS 또는 Linux 터미널, Python 3.12 이상, [`uv`](https://docs.astral.sh/uv/getting-started/installation/)
* `SANDBOX_USER` 액션이 포함된 [CoreWeave API 액세스 토큰](/ko/products/sandboxes/placement#choose-and-get-credentials)
* [Pi에서 지원하는 모델 공급자](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md)의 사용자 인증 정보. 이 가이드에서는 Serverless Inference를 사용하며, 이를 사용하려면 [추론 크레딧](/ko/products/inference/serverless/api-reference#prerequisites)이 필요합니다.
* 공개 Git 저장소 URL. 비공개 저장소를 사용하려면 샌드박스 내에서 별도로 Git 인증을 설정해야 합니다.

<h2 id="prepare-your-local-environment">
  로컬 환경 준비하기
</h2>

로컬 프로젝트를 만들고 Sandboxes SDK(소프트웨어 개발 키트)를 설치하세요.

```bash theme={"system"}
uv init --bare pi-sandbox
cd pi-sandbox
uv venv --python 3.12
source .venv/bin/activate
uv pip install 'cwsandbox==1.14.2'
```

같은 터미널에서 `[API-ACCESS-TOKEN]`을 CoreWeave API 액세스 토큰으로 바꾸세요.

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

SDK는 이 로컬 사용자 인증 정보를 사용해 샌드박스를 관리합니다. 생성 스크립트는 이 사용자 인증 정보를 샌드박스로 복사하지 않습니다. 모델 인증은 별도로 설정하세요.

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

다음 스크립트를 `create_pi_sandbox.py`로 저장하세요. 이 스크립트는 CPU 샌드박스를 생성하고 Pi `0.87.1`을 설치한 다음 저장소를 복제합니다. 런타임과 Git은 Node.js 이미지에서 제공됩니다. 설정 중 실패가 발생하면 스크립트는 오류를 발생시키기 전에 샌드박스를 중지합니다.

```python title="create_pi_sandbox.py" theme={"system"}
import sys

from cwsandbox import Sandbox

if len(sys.argv) != 2:
    raise SystemExit("Pass a repository URL.")

sandbox = Sandbox.run(
    placement_mode="serverless",
    container_image="node:22-bookworm",
    resources={"cpu": "2", "memory": "4Gi"},
    max_lifetime_seconds=4 * 3600,
    tags=["pi-cli"],
)
print(f"Sandbox ID: {sandbox.sandbox_id}", flush=True)
try:
    sandbox.wait()
    commands = [
        ["npm", "install", "--global", "--ignore-scripts", "@earendil-works/pi-coding-agent@0.87.1"],
        ["mkdir", "-p", "/workspace"],
        ["git", "clone", "--", sys.argv[1], "/workspace/project"],
        ["pi", "--version"],
    ]
    for command in commands:
        result = sandbox.exec(command, timeout_seconds=900, check=True).result()
        print(result.stdout, end="")
except BaseException:
    sandbox.stop().result()
    raise
```

`[REPOSITORY-URL]`을 사용 중인 저장소 URL로 바꾼 후 다음 명령을 실행하세요.

```bash theme={"system"}
python create_pi_sandbox.py [REPOSITORY-URL]
```

출력된 샌드박스 ID를 기록해 두세요. 설정에 성공하면 Pi 버전 `0.87.1`이 출력됩니다. 스크립트가 종료된 후에도 샌드박스는 직접 중지하거나 4시간의 수명이 만료될 때까지 계속 실행됩니다. 수명에는 시작 시간도 포함됩니다.

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

다음 코드를 `attach_sandbox.py`로 저장하세요. 이 스크립트는 터미널 입력을 샌드박스의 Bash 셸로 전달하고, 셸이 종료되면 로컬 터미널 설정을 원래대로 복원합니다.

```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)
```

`[SANDBOX-ID]`를 실제 샌드박스 ID로 바꾸세요:

```bash theme={"system"}
python attach_sandbox.py [SANDBOX-ID]
```

샌드박스의 Bash 프롬프트에서 복제한 저장소로 이동하세요.

```bash theme={"system"}
cd /workspace/project
```

이 셸에서 다음 섹션에 나오는 공급자 설정 명령어와 Pi 명령어를 실행하세요.

<h2 id="choose-a-model-provider">
  모델 공급자 선택
</h2>

다음 옵션 중 하나를 선택하세요. 이 가이드에서는 샌드박스 인증과 모델 인증에 각각 별도의 사용자 인증 정보를 사용합니다. Pi는 자신의 프로세스에 제공된 사용자 인증 정보에 액세스할 수 있으며, 워크스페이스의 콘텐츠를 선택한 모델 공급자에게 전송할 수 있습니다.

<h3 id="use-serverless-inference">
  Serverless Inference 사용
</h3>

이 워크스루에서는 [Serverless Inference](/ko/products/inference/serverless)를 사용하는 것을 권장합니다. 예시에서는 `zai-org/GLM-5.2`를 사용합니다. 작업에 더 적합한 모델이 있다면 [모델 카탈로그](/ko/products/inference/serverless/models)에서 다른 모델을 선택하세요.

샌드박스 셸에 입력 내용이 표시되지 않는 프롬프트가 나타나면 추론 크레딧이 있는 계정의 Forge API 키를 입력하세요.

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

샌드박스 셸에서 Pi의 OpenAI 호환 공급자를 설정하세요. 다음 명령어를 실행하면 `~/.pi/agent/models.json` 파일이 생성됩니다. 따옴표로 감싼 heredoc은 환경 변수 참조를 그대로 유지하므로 파일에 키가 직접 저장되지 않습니다.

```bash theme={"system"}
mkdir -p ~/.pi/agent
cat > ~/.pi/agent/models.json <<'JSON'
{
  "providers": {
    "forge": {
      "baseUrl": "https://api.inference.wandb.ai/v1",
      "api": "openai-completions",
      "apiKey": "${FORGE_INFERENCE_API_KEY}",
      "models": [
        {
          "id": "zai-org/GLM-5.2",
          "name": "GLM 5.2 (Forge)",
          "reasoning": true,
          "input": ["text"],
          "contextWindow": 1048576,
          "maxTokens": 8192
        }
      ]
    }
  }
}
JSON
pi --provider forge --model zai-org/GLM-5.2
```

Pi를 실행하면 상태 영역에 `/workspace/project`와 `zai-org/GLM-5.2`가 표시된 터미널 인터페이스가 열립니다. 모델 액세스를 확인하려면 [Pi 실행 및 작업 결과 확인](#run-pi-and-check-its-work)의 안내에 따라 작업을 제출하세요.

이 설정에서는 응답당 최대 8,192 토큰으로 제한됩니다. 모델을 변경하는 경우 공급자에 맞게 모델 ID와 기능을 업데이트하세요. 그 밖의 설정 옵션은 [Pi 모델 구성](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md)을 참조하세요.

<h3 id="use-another-provider">
  다른 공급자 사용
</h3>

Anthropic 또는 OpenAI를 직접 사용하려면 해당 API 키를 선택하고 같은 샌드박스 셸에서 Pi를 시작하세요.

<Tabs>
  <Tab title="Anthropic">
    ```bash theme={"system"}
    read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
    export ANTHROPIC_API_KEY
    printf '\n'
    pi --provider anthropic
    ```
  </Tab>

  <Tab title="OpenAI">
    ```bash theme={"system"}
    read -r -s -p 'OpenAI API key: ' OPENAI_API_KEY
    export OPENAI_API_KEY
    printf '\n'
    pi --provider openai
    ```
  </Tab>
</Tabs>

Pi에서 `/model`을 사용해 해당 공급자에서 사용 가능한 모델을 선택하세요. 다른 공급자와 계정 로그인 옵션은 사전 요구 사항에 링크된 Pi 공급자 문서를 참고하세요.

<h2 id="run-pi-and-check-its-work">
  Pi 실행 및 작업 결과 확인
</h2>

Pi에 프로젝트 신뢰 프롬프트가 표시되면 안내에 따르세요. Pi가 복제된 저장소에서 파일을 생성하고 조회할 수 있는지 확인하려면 Pi에 다음 작업을 제출하세요.

```text theme={"system"}
현재 디렉터리에 정확히 "Hello from CoreWeave"라는 내용을 담은 sandbox-proof.txt를 만든 다음, 해당 파일을 다시 읽어 주세요.
```

Pi는 파일을 읽고, 쓰고, 편집할 수 있으며 셸 명령어도 실행할 수 있습니다. Pi의 도구는 샌드박스 프로세스의 권한으로 동작합니다. 저장소와 로드하는 모든 Pi 확장을 검토하세요. 자세한 내용은 [Pi 보안](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md)을 참조하세요.

Pi가 작업을 마치면 `/quit`을 입력하여 샌드박스 셸로 돌아가세요. Pi는 `pi --session` 명령어가 포함된 `To resume this session:` 줄을 출력합니다. 나중에 이 대화를 다시 열 수 있도록 해당 명령어를 보관해 두세요.

파일을 직접 확인하세요:

```bash theme={"system"}
cat /workspace/project/sandbox-proof.txt
```

출력에 `Hello from CoreWeave`가 포함되어 있어야 합니다.

Forge 설정으로 사용자 개입 없이 작업을 실행하려면 같은 셸에서 Pi를 print 모드로 실행하세요.

```bash theme={"system"}
pi --provider forge --model zai-org/GLM-5.2 --print 'Read sandbox-proof.txt and report its contents.'
```

print 모드에서는 프롬프트를 처리하고 Pi의 응답을 출력한 다음 종료합니다. 다른 공급자를 사용하려면 공급자 및 모델 인수를 원하는 값으로 바꾸세요.

<h2 id="reconnect-to-a-conversation">
  대화에 다시 연결하기
</h2>

샌드박스가 실행 중일 때 다시 연결하려면 `attach_sandbox.py` 스크립트를 다시 실행하세요. Pi를 시작하기 전에 이전 셸에서 입력했던 API 키를 다시 입력하고 `/workspace/project` 디렉터리로 이동하세요. 대화형 대화를 다시 열려면 `[SESSION-ID]`를 Pi 종료 시 출력된 `To resume this session:` 줄의 ID로 바꾸세요:

```bash theme={"system"}
pi --session [SESSION-ID]
```

또는 `pi --continue`를 사용하면 해당 프로젝트의 가장 최근 세션을 재개할 수 있습니다. 대화형으로 대화를 나눈 뒤 print 모드 예시를 실행했다면 print 모드 세션이 재개됩니다. 특정 대화로 돌아가려면 `--session`을 사용하세요.

<h2 id="retrieve-the-result-and-stop">
  결과 조회 및 중지
</h2>

`exit`를 입력하여 샌드박스 셸을 종료하세요. 로컬 터미널에서 다음 코드를 `collect_pi_result.py` 파일로 저장하세요.

```python title="collect_pi_result.py" theme={"system"}
import sys
from pathlib import Path

from cwsandbox import Sandbox

if len(sys.argv) != 2:
    raise SystemExit("Pass a sandbox ID.")

sandbox = Sandbox.from_id(sys.argv[1]).result()
content = sandbox.read_file("/workspace/project/sandbox-proof.txt").result()
Path("sandbox-proof.txt").write_bytes(content)
print(content.decode(), end="")
sandbox.stop().result()
```

파일을 로컬에 저장하고 컴퓨팅을 중지하려면 `[SANDBOX-ID]`를 사용자의 샌드박스 ID로 바꾼 다음 스크립트를 실행하세요.

```bash theme={"system"}
python collect_pi_result.py [SANDBOX-ID]
```

이 스크립트는 파일을 조회한 후에만 샌드박스를 중지합니다. 조회에 실패하면 오류를 수정한 후 다시 시도하세요. 파일이 더 이상 필요하지 않을 때 샌드박스를 따로 중지하려면 다음 내용을 `stop_pi_sandbox.py`로 저장하세요.

```python title="stop_pi_sandbox.py" theme={"system"}
import sys

from cwsandbox import Sandbox

if len(sys.argv) != 2:
    raise SystemExit("Pass a sandbox ID.")

sandbox = Sandbox.from_id(sys.argv[1]).result()
sandbox.stop().result()
```

샌드박스 ID를 지정하여 스크립트를 실행하세요.

```bash theme={"system"}
python stop_pi_sandbox.py [SANDBOX-ID]
```

Pi나 셸을 종료해도 샌드박스는 중지되지 않습니다. 이 예제에는 영구 마운트가 없으므로, 샌드박스를 중지하거나 샌드박스가 만료되기 전에 필요한 파일을 가져오세요. 새 샌드박스에 복원할 수 있는 워크스페이스가 필요하다면 샌드박스를 생성할 때 [파일 시스템 스냅샷](/ko/products/sandboxes/file-system-snapshots)을 설정하세요.

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

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

* 샌드박스 생성에 실패하면 샌드박스 사용자 인증 정보를 확인하고, 사전 요구 사항에 링크된 샌드박스 인증 요구 사항도 확인하세요.
* Pi가 인증하지 못하면 Pi를 시작하는 셸에서 모델 사용자 인증 정보가 export되어 있는지 확인하세요. Forge를 사용하는 경우 추론 크레딧과 모델 ID도 확인하세요.
* Pi가 공급자에 연결하지 못하면 공급자 엔드포인트에 대한 아웃바운드 액세스를 확인하세요. 설치 및 복제 작업에는 npm과 Git 호스트에 대한 액세스도 필요합니다.
* 연결이 끊기면 샌드박스가 실행 중일 때 다시 연결하세요. 터미널 연결이 끊겨도 프로세스가 계속 실행되어야 한다면 `tmux`와 같은 터미널 멀티플렉서를 사용하세요.

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

자세한 내용은 다음 리소스를 참조하세요.

* [대화형 셸](/ko/products/sandboxes/client/guides/interactive-shells)에서는 SDK를 통한 터미널 액세스 방법을 다룹니다.
* [파일 작업](/ko/products/sandboxes/client/guides/file-operations)에서는 워크스페이스 파일을 업로드하고 조회하는 방법을 다룹니다.
* [Pi 문서](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs)에서는 세션, 모델 선택, 확장 기능을 다룹니다.