Exécuter Pi dans une sandbox

Exécutez Pi dans une sandbox CoreWeave pour travailler sur un dépôt depuis votre terminal. Le processus de l’agent Pi, ses fichiers et ses commandes shell s’exécutent dans la sandbox, tandis que les requêtes au modèle sont envoyées au fournisseur de votre choix. Ce guide explique comment créer le Workspace, vous connecter à Pi, vérifier son travail et arrêter les ressources de calcul.

Prérequis

Avant de commencer, vous devez disposer des éléments suivants :

Un terminal macOS ou Linux avec soit Python 3.12 ou version ultérieure et uv, soit Node.js 22 ou version ultérieure.
Une clé API Forge ou un jeton d’accès à l’API CoreWeave.
Des identifiants d’authentification pour un fournisseur de modèles pris en charge par Pi. Ce guide utilise Serverless Inference, qui nécessite des crédits d’inférence.
L’URL d’un dépôt Git public. Pour les dépôts privés, une authentification Git distincte est nécessaire dans la sandbox.

Choisir les identifiants d’authentification de la sandbox

Ces exemples utilisent la capacité sans serveur. Les deux types d’identifiants d’authentification prennent en charge les bacs à sable sans serveur. Pour obtenir l’un ou l’autre, consultez Choisir et obtenir des identifiants d’authentification. Les identifiants d’authentification de l’agent et du fournisseur de modèles se configurent séparément. Après avoir créé votre projet local dans la section suivante, enregistrez sandbox_auth.py ou sandbox-client.mts, selon votre langage, dans le même répertoire que les scripts que vous exécuterez dans ce guide. Utilisez ce même fichier pour la création, la reconnexion et le nettoyage. Il conserve votre choix de méthode d’authentification, et non la clé elle-même.

Clé API Forge
Jeton d’accès à l’API CoreWeave

Remplacez [WANDB-API-KEY] par votre clé API Forge et exportez-la dans votre terminal local :

export WANDB_API_KEY="[WANDB-API-KEY]"

Python
TypeScript

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.WANDB

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/wandb";

export const client = createSandboxClientFromEnv();

Remplacez [API-ACCESS-TOKEN] par votre jeton d’accès à l’API CoreWeave et exportez-le dans votre terminal local :

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

Python
TypeScript

sandbox_auth.py

from cwsandbox import AuthStrategy

AUTH = AuthStrategy.COREWEAVE_API_KEY

sandbox-client.mts

import { createSandboxClientFromEnv } from "@coreweave/cwsandbox/node";

export const client = createSandboxClientFromEnv();

Préparer votre environnement local

Créez un projet local et installez le kit de développement logiciel (SDK) Sandbox :

Python
TypeScript

uv init --bare pi-sandbox
cd pi-sandbox
uv venv --python 3.12
source .venv/bin/activate
uv pip install 'cwsandbox[wandb]==1.14.2'

mkdir pi-sandbox
cd pi-sandbox
npm install @coreweave/cwsandbox@1.0.0 tsx

Le SDK utilise l’identifiant d’authentification local que vous avez sélectionné pour gérer la sandbox. Le script de création ne le copie pas dans la sandbox. L’authentification du modèle se configure séparément.

Créer la sandbox

Enregistrez le script correspondant à votre langage sous le nom create_pi_sandbox.py ou create_pi_sandbox.mts. Il crée une sandbox CPU, installe Pi 0.87.1 et clone le dépôt. L’image Node.js fournit l’environnement d’exécution ainsi que Git. En cas d’échec de la configuration, le script arrête la sandbox avant de signaler l’erreur.

Python
TypeScript

create_pi_sandbox.py

import sys

from cwsandbox import Sandbox
from sandbox_auth import AUTH

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"],
    auth=AUTH,
)
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

create_pi_sandbox.mts

import { client } from "./sandbox-client.mts";

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

const sandbox = await client.create({
  containerImage: "node:22-bookworm",
  resources: { cpu: "2", memory: "4Gi" },
  maxLifetimeSeconds: 4 * 3600,
  waitUntilRunning: false,
  tags: ["pi-cli"],
});
console.log(`Sandbox ID: ${sandbox.sandboxId}`);
try {
  await sandbox.wait();
  const commands = [
    ["npm", "install", "--global", "--ignore-scripts", "@earendil-works/pi-coding-agent@0.87.1"],
    ["mkdir", "-p", "/workspace"],
    ["git", "clone", "--", repository, "/workspace/project"],
    ["pi", "--version"],
  ];
  for (const command of commands) {
    const result = await sandbox.commands.run(command, { timeoutMs: 900_000, check: true });
    process.stdout.write(result.stdout);
  }
} catch (error) {
  await sandbox.stop();
  throw error;
}

Remplacez [REPOSITORY-URL] par l’URL de votre dépôt, puis exécutez :

Python
TypeScript

python create_pi_sandbox.py [REPOSITORY-URL]

npx tsx create_pi_sandbox.mts [REPOSITORY-URL]

Notez l’ID de la sandbox qui s’affiche. Si la configuration réussit, la version de Pi, 0.87.1, s’affiche. La sandbox continue de s’exécuter une fois le script terminé, jusqu’à ce que vous l’arrêtiez ou que sa durée de vie de 4 heures arrive à expiration. La durée de vie inclut le temps de démarrage.

Connecter votre terminal

Enregistrez le script correspondant à votre langage sous le nom attach_sandbox.py ou attach_sandbox.mts. Il transmet les entrées de votre terminal à un shell Bash dans la sandbox, puis restaure les paramètres de votre terminal local à la fermeture du shell.

Python
TypeScript

attach_sandbox.py

import os
import shutil
import sys
import termios
import threading
import tty

from cwsandbox import Sandbox
from sandbox_auth import AUTH

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], auth=AUTH).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)

attach_sandbox.mts

import { client } from "./sandbox-client.mts";

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 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();
}

Remplacez [SANDBOX-ID] par l’ID de votre sandbox :

Python
TypeScript

python attach_sandbox.py [SANDBOX-ID]

npx tsx attach_sandbox.mts [SANDBOX-ID]

À l’invite Bash du sandbox, accédez au dépôt cloné :

cd /workspace/project

Dans ce shell, exécutez les commandes de configuration du fournisseur et les commandes Pi présentées dans les sections suivantes.

Choisir un fournisseur de modèle

Choisissez l’une des options suivantes. Dans ce guide, l’authentification auprès de la sandbox et celle auprès du modèle reposent sur des identifiants d’authentification distincts. Pi peut accéder aux identifiants d’authentification fournis à son processus et peut envoyer le contenu du Workspace au fournisseur de modèle sélectionné.

Utiliser Serverless Inference

Nous vous recommandons Serverless Inference pour ce guide pas à pas. L’exemple utilise zai-org/GLM-5.2. Si un autre modèle du catalogue de modèles convient mieux à votre tâche, choisissez-le. Dans le shell de la sandbox, à l’invite masquée, saisissez une clé API Forge associée à un compte disposant de crédits d’inférence :

read -r -s -p 'Forge inference API key: ' WANDB_API_KEY
export WANDB_API_KEY
printf '\n'

Dans le shell de la sandbox, configurez le fournisseur compatible avec OpenAI de Pi. Les commandes suivantes créent le fichier ~/.pi/agent/models.json. Comme le heredoc est entre guillemets, la référence à la variable d’environnement est conservée telle quelle et la clé n’apparaît pas dans le fichier :

mkdir -p ~/.pi/agent
cat > ~/.pi/agent/models.json <<'JSON'
{
  "providers": {
    "forge": {
      "baseUrl": "https://api.inference.wandb.ai/v1",
      "api": "openai-completions",
      "apiKey": "${WANDB_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 ouvre son interface de terminal avec /workspace/project et zai-org/GLM-5.2 dans la zone de statut. Soumettez une tâche comme indiqué dans Exécuter Pi et vérifier son travail pour vérifier l’accès au modèle. La configuration limite chaque réponse à 8 192 jetons. Si vous changez de modèle, mettez à jour l’ID du modèle et ses capacités en fonction du fournisseur. Pour découvrir d’autres options de configuration, consultez Configuration du modèle Pi.

Utiliser un autre fournisseur

Pour utiliser directement Anthropic ou OpenAI, choisissez la clé API correspondante et lancez Pi dans le même shell de la sandbox :

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

Utilisez /model dans Pi pour choisir un modèle disponible auprès de votre fournisseur. La documentation de Pi sur les fournisseurs, dont le lien figure dans les prérequis, présente les autres fournisseurs ainsi que les options de connexion par compte.

Exécuter Pi et vérifier son travail

Si Pi affiche une demande de confiance pour le projet, suivez les instructions. Pour vérifier que Pi peut créer et lire un fichier dans le dépôt cloné, soumettez cette tâche dans Pi :

Créez sandbox-proof.txt dans le répertoire courant avec exactement le contenu « Hello from CoreWeave », puis relisez-le.

Pi peut lire, écrire et modifier des fichiers, ainsi qu’exécuter des commandes shell. Ses outils s’exécutent avec les autorisations du processus de la sandbox. Examinez le dépôt ainsi que toutes les extensions Pi que vous chargez. Voir Sécurité de Pi. Une fois que Pi a terminé, saisissez /quit pour revenir au shell de la sandbox. Pi affiche une ligne To resume this session: suivie d’une commande pi --session. Conservez cette commande pour rouvrir cette conversation. Vérifiez le fichier par vous-même :

cat /workspace/project/sandbox-proof.txt

La sortie doit contenir Hello from CoreWeave. Pour exécuter une tâche sans intervention avec la configuration Forge, lancez Pi en mode impression depuis le même shell :

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

Le mode impression traite le prompt, affiche la réponse de Pi, puis s’arrête. Pour utiliser un autre fournisseur, remplacez les arguments de fournisseur et de modèle par ceux de votre choix.

Se reconnecter à une conversation

Pour vous reconnecter pendant que le sandbox est en cours d’exécution, exécutez de nouveau le script d’attachement. Ressaisissez les clés API que vous aviez fournies dans le shell précédent, puis revenez au répertoire /workspace/project avant de démarrer Pi. Pour rouvrir votre conversation interactive, remplacez [SESSION-ID] par l’ID indiqué sur la ligne To resume this session: que Pi a affichée lorsque vous l’avez quitté :

pi --session [SESSION-ID]

Vous pouvez également utiliser pi --continue pour reprendre la session la plus récente du projet. Si vous avez exécuté l’exemple en mode impression après votre conversation interactive, c’est la session en mode impression qui est reprise. Pour revenir à une conversation précise, utilisez --session.

Récupérer le résultat et arrêter la sandbox

Saisissez exit pour quitter le shell de la sandbox. Dans votre terminal local, enregistrez le script correspondant à votre langage sous le nom collect_pi_result.py ou collect_pi_result.mts :

Python
TypeScript

collect_pi_result.py

import sys
from pathlib import Path

from cwsandbox import Sandbox
from sandbox_auth import AUTH

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

sandbox = Sandbox.from_id(sys.argv[1], auth=AUTH).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()

collect_pi_result.mts

import { writeFile } from "node:fs/promises";

import { client } from "./sandbox-client.mts";

const sandboxId = process.argv[2];
if (!sandboxId) throw new Error("Pass a sandbox ID.");

const sandbox = await client.fromId(sandboxId);
const content = await sandbox.files.read("/workspace/project/sandbox-proof.txt");
await writeFile("sandbox-proof.txt", content);
process.stdout.write(new TextDecoder().decode(content));
await sandbox.stop();

Pour enregistrer le fichier en local et libérer les ressources de calcul, remplacez [SANDBOX-ID] par l’ID de votre sandbox et exécutez le script :

Python
TypeScript

python collect_pi_result.py [SANDBOX-ID]

npx tsx collect_pi_result.mts [SANDBOX-ID]

Ce script n’arrête la sandbox qu’une fois le fichier récupéré. Si la récupération échoue, corrigez l’erreur et réessayez. Pour arrêter la sandbox indépendamment, lorsque vous n’avez plus besoin de ses fichiers, enregistrez le script correspondant à votre langage sous le nom stop_pi_sandbox.py ou stop_pi_sandbox.mts :

Python
TypeScript

stop_pi_sandbox.py

import sys

from cwsandbox import Sandbox
from sandbox_auth import AUTH

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

sandbox = Sandbox.from_id(sys.argv[1], auth=AUTH).result()
sandbox.stop().result()

stop_pi_sandbox.mts

import { client } from "./sandbox-client.mts";

const sandboxId = process.argv[2];
if (!sandboxId) throw new Error("Pass a sandbox ID.");

const sandbox = await client.fromId(sandboxId);
await sandbox.stop();

Exécutez le script avec l’ID de votre sandbox :

Python
TypeScript

python stop_pi_sandbox.py [SANDBOX-ID]

npx tsx stop_pi_sandbox.mts [SANDBOX-ID]

Quitter Pi ou le shell n’arrête pas la sandbox. Cet exemple n’utilise aucun montage persistant : récupérez tous les fichiers nécessaires avant l’arrêt ou l’expiration de la sandbox. Pour obtenir un workspace restaurable dans une nouvelle sandbox, configurez des instantanés du système de fichiers dès la création.

Dépannage

Effectuez les vérifications suivantes pour résoudre les problèmes courants :

Si la création du sandbox échoue, vérifiez l’identifiant d’authentification de votre sandbox ainsi que les exigences d’authentification des sandboxes, dont le lien figure dans les prérequis.
Si Pi ne parvient pas à s’authentifier, vérifiez que l’identifiant d’authentification du modèle est exporté dans le shell qui lance Pi. Avec Forge, vérifiez également vos crédits d’inférence et l’ID du modèle.
Si Pi ne parvient pas à joindre son fournisseur, vérifiez l’accès sortant au point de terminaison du fournisseur. L’installation et le clonage nécessitent également un accès à npm et à votre hébergeur Git.
Si votre connexion est interrompue, rattachez-vous au sandbox tant qu’il est en cours d’exécution. Pour qu’un processus survive aux déconnexions du terminal, utilisez un multiplexeur de terminal tel que tmux.

Étapes suivantes

Pour plus d’informations, voir les ressources suivantes :

Shells interactifs explique comment accéder au terminal via le SDK.
Opérations sur les fichiers explique comment téléverser et récupérer les fichiers du Workspace.
La documentation de Pi présente les sessions, la sélection de modèle et les extensions.

Sandbox

Utiliser les Sandbox

Gérer les bacs à sable

Référence

Exécuter Pi dans une sandbox

Prérequis

Choisir les identifiants d’authentification de la sandbox

Préparer votre environnement local

Créer la sandbox

Connecter votre terminal

Choisir un fournisseur de modèle

Utiliser Serverless Inference

Utiliser un autre fournisseur

Exécuter Pi et vérifier son travail

Se reconnecter à une conversation

Récupérer le résultat et arrêter la sandbox

Dépannage

Étapes suivantes

​Prérequis

​Choisir les identifiants d’authentification de la sandbox

​Préparer votre environnement local

​Créer la sandbox

​Connecter votre terminal

​Choisir un fournisseur de modèle

​Utiliser Serverless Inference

​Utiliser un autre fournisseur

​Exécuter Pi et vérifier son travail

​Se reconnecter à une conversation

​Récupérer le résultat et arrêter la sandbox

​Dépannage

​Étapes suivantes

Prérequis

Choisir les identifiants d’authentification de la sandbox

Préparer votre environnement local

Créer la sandbox

Connecter votre terminal

Choisir un fournisseur de modèle

Utiliser Serverless Inference

Utiliser un autre fournisseur

Exécuter Pi et vérifier son travail

Se reconnecter à une conversation

Récupérer le résultat et arrêter la sandbox

Dépannage

Étapes suivantes