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, Python 3.12 ou version ultérieure, et uv.
Un jeton d’accès à l’API CoreWeave doté de l’action SANDBOX_USER.
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.

Préparer votre environnement local

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

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

Dans le même terminal, remplacez [API-ACCESS-TOKEN] par votre jeton d’accès à l’API CoreWeave :

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

Le SDK utilise cet identifiant d’authentification local 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 suivant sous le nom create_pi_sandbox.py. 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 lever l’erreur.

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

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

python create_pi_sandbox.py [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 code suivant sous le nom attach_sandbox.py. 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.

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)

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

python attach_sandbox.py [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: ' FORGE_INFERENCE_API_KEY
export FORGE_INFERENCE_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": "${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 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 attach_sandbox.py. 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 code suivant sous le nom 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()

Pour enregistrer le fichier en local et arrêter le calcul, remplacez [SANDBOX-ID] par l’ID de votre sandbox, puis exécutez le script :

python collect_pi_result.py [SANDBOX-ID]

Ce script n’arrête la sandbox qu’après avoir récupéré le fichier. Si la récupération échoue, corrigez l’erreur et réessayez. Pour arrêter la sandbox séparément lorsque vous n’avez plus besoin de ses fichiers, enregistrez le code suivant sous 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()

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

python stop_pi_sandbox.py [SANDBOX-ID]

Quitter Pi ou le shell n’arrête pas la sandbox. Cet exemple n’utilise aucun montage persistant. Récupérez les fichiers dont vous avez besoin avant l’arrêt ou l’expiration de la sandbox. Pour disposer d’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

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

​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

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