샌드박스에서 Pi 실행하기

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

사전 요구 사항

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

macOS 또는 Linux 터미널, Python 3.12 이상, uv
SANDBOX_USER 액션이 포함된 CoreWeave API 액세스 토큰
Pi에서 지원하는 모델 공급자의 사용자 인증 정보. 이 가이드에서는 Serverless Inference를 사용하며, 이를 사용하려면 추론 크레딧이 필요합니다.
공개 Git 저장소 URL. 비공개 저장소를 사용하려면 샌드박스 내에서 별도로 Git 인증을 설정해야 합니다.

로컬 환경 준비하기

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

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 액세스 토큰으로 바꾸세요.

export CWSANDBOX_API_KEY="[API-ACCESS-TOKEN]"

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

샌드박스 생성

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

create_pi_sandbox.py

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로 바꾼 후 다음 명령을 실행하세요.

python create_pi_sandbox.py [REPOSITORY-URL]

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

터미널 연결하기

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

attach_sandbox.py

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로 바꾸세요:

python attach_sandbox.py [SANDBOX-ID]

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

cd /workspace/project

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

모델 공급자 선택

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

Serverless Inference 사용

이 워크스루에서는 Serverless Inference를 사용하는 것을 권장합니다. 예시에서는 zai-org/GLM-5.2를 사용합니다. 작업에 더 적합한 모델이 있다면 모델 카탈로그에서 다른 모델을 선택하세요. 샌드박스 셸에 입력 내용이 표시되지 않는 프롬프트가 나타나면 추론 크레딧이 있는 계정의 Forge API 키를 입력하세요.

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은 환경 변수 참조를 그대로 유지하므로 파일에 키가 직접 저장되지 않습니다.

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 실행 및 작업 결과 확인의 안내에 따라 작업을 제출하세요. 이 설정에서는 응답당 최대 8,192 토큰으로 제한됩니다. 모델을 변경하는 경우 공급자에 맞게 모델 ID와 기능을 업데이트하세요. 그 밖의 설정 옵션은 Pi 모델 구성을 참조하세요.

다른 공급자 사용

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

Anthropic
OpenAI

read -r -s -p 'Anthropic API key: ' ANTHROPIC_API_KEY
export ANTHROPIC_API_KEY
printf '\n'
pi --provider anthropic

read -r -s -p 'OpenAI API key: ' OPENAI_API_KEY
export OPENAI_API_KEY
printf '\n'
pi --provider openai

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

Pi 실행 및 작업 결과 확인

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

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

Pi는 파일을 읽고, 쓰고, 편집할 수 있으며 셸 명령어도 실행할 수 있습니다. Pi의 도구는 샌드박스 프로세스의 권한으로 동작합니다. 저장소와 로드하는 모든 Pi 확장을 검토하세요. 자세한 내용은 Pi 보안을 참조하세요. Pi가 작업을 마치면 /quit을 입력하여 샌드박스 셸로 돌아가세요. Pi는 pi --session 명령어가 포함된 To resume this session: 줄을 출력합니다. 나중에 이 대화를 다시 열 수 있도록 해당 명령어를 보관해 두세요. 파일을 직접 확인하세요:

cat /workspace/project/sandbox-proof.txt

출력에 Hello from CoreWeave가 포함되어 있어야 합니다. Forge 설정으로 사용자 개입 없이 작업을 실행하려면 같은 셸에서 Pi를 print 모드로 실행하세요.

pi --provider forge --model zai-org/GLM-5.2 --print 'Read sandbox-proof.txt and report its contents.'

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

대화에 다시 연결하기

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

pi --session [SESSION-ID]

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

결과 조회 및 중지

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

collect_pi_result.py

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로 바꾼 다음 스크립트를 실행하세요.

python collect_pi_result.py [SANDBOX-ID]

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

stop_pi_sandbox.py

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를 지정하여 스크립트를 실행하세요.

python stop_pi_sandbox.py [SANDBOX-ID]

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

문제 해결

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

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

다음 단계

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

대화형 셸에서는 SDK를 통한 터미널 액세스 방법을 다룹니다.
파일 작업에서는 워크스페이스 파일을 업로드하고 조회하는 방법을 다룹니다.
Pi 문서에서는 세션, 모델 선택, 확장 기능을 다룹니다.

샌드박스

샌드박스 사용하기

샌드박스 관리

레퍼런스

샌드박스에서 Pi 실행하기

사전 요구 사항

로컬 환경 준비하기

샌드박스 생성

터미널 연결하기

모델 공급자 선택

Serverless Inference 사용

다른 공급자 사용

Pi 실행 및 작업 결과 확인

대화에 다시 연결하기

결과 조회 및 중지

문제 해결

다음 단계

​사전 요구 사항

​로컬 환경 준비하기

​샌드박스 생성

​터미널 연결하기

​모델 공급자 선택

​Serverless Inference 사용

​다른 공급자 사용

​Pi 실행 및 작업 결과 확인

​대화에 다시 연결하기

​결과 조회 및 중지

​문제 해결

​다음 단계

사전 요구 사항

로컬 환경 준비하기

샌드박스 생성

터미널 연결하기

모델 공급자 선택

Serverless Inference 사용

다른 공급자 사용

Pi 실행 및 작업 결과 확인

대화에 다시 연결하기

결과 조회 및 중지

문제 해결

다음 단계