サンドボックスで Pi を実行する

CoreWeave のサンドボックス内で Pi を実行すると、ターミナルからリポジトリを操作して作業できます。Pi のエージェントプロセス、ファイル、シェルコマンドはすべてサンドボックス内で実行され、モデルへのリクエストは選択したプロバイダーに送信されます。このガイドでは、ワークスペースの作成、Pi への接続、作業内容の確認、コンピュートの停止までの手順を説明します。

前提条件

始める前に、以下を用意してください。

macOS または Linux のターミナル、Python 3.12 以降、および uv。
SANDBOX_USER action が付与された CoreWeave API アクセストークン。
Pi がサポートするモデルプロバイダーの認証情報。このガイドでは Serverless Inference を使用します。Serverless Inference の利用には推論クレジットが必要です。
公開 Git リポジトリの URL。非公開リポジトリを使用する場合は、サンドボックス内で別途 Git の認証を設定する必要があります。

ローカル環境を準備する

ローカルプロジェクトを作成し、サンドボックスのソフトウェア開発キット (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 ファイルが作成されます。ヒアドキュメントの区切り文字を引用符で囲んでいるため、環境変数の参照は展開されずにそのまま保持されます。これにより、ファイルにキーが書き込まれることはありません。

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 security を参照してください。 Pi の処理が終了したら、/quit を入力してサンドボックスのシェルに戻ります。Pi は pi --session コマンドを含む To resume this session: 行を出力します。この会話を再開できるよう、このコマンドを控えておいてください。ファイルを Pi とは別に検証します。

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 を実行すると、その project で最後に使用したセッションが再開されます。対話型の会話の後に 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 を起動するシェルでモデルの認証情報がエクスポートされていることを確認してください。Forge を使用している場合は、推論クレジットとモデル ID も確認してください。
Pi がプロバイダーに接続できない場合は、プロバイダーのエンドポイントへのアウトバウンドアクセスを確認してください。インストールとクローンには、npm と Git ホストへのアクセスも必要です。
接続が切断された場合は、サンドボックスの実行中に再度アタッチしてください。ターミナルが切断されてもプロセスを継続させる必要がある場合は、tmux などのターミナルマルチプレクサーを使用してください。

次のステップ

詳細については、次のリソースを参照してください。

インタラクティブシェルでは、SDK を使用したターミナルアクセスについて説明しています。
ファイル操作では、ワークスペース内のファイルのアップロードと取得について説明しています。
Pi のドキュメントでは、セッション、モデル選択、拡張機能について説明しています。