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

# Exécuter Pi dans une sandbox

> Exécutez Pi depuis un terminal connecté, avec Serverless Inference en option, puis récupérez votre travail.

Exécutez [Pi](https://github.com/earendil-works/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.

<h2 id="prerequisites">
  Prérequis
</h2>

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

* Un terminal macOS ou Linux, Python 3.12 ou version ultérieure, et [`uv`](https://docs.astral.sh/uv/getting-started/installation/).
* Un [jeton d’accès à l’API CoreWeave](/fr/products/sandboxes/placement#choose-and-get-credentials) doté de l’action `SANDBOX_USER`.
* Des identifiants d’authentification pour un [fournisseur de modèles pris en charge par Pi](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/providers.md). Ce guide utilise Serverless Inference, qui nécessite des [crédits d’inférence](/fr/products/inference/serverless/api-reference#prerequisites).
* 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.

<h2 id="prepare-your-local-environment">
  Préparer votre environnement local
</h2>

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

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

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

```bash theme={"system"}
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.

<h2 id="create-the-sandbox">
  Créer la sandbox
</h2>

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.

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

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

```bash theme={"system"}
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.

<h2 id="attach-your-terminal">
  Connecter votre terminal
</h2>

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.

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

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

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

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

```bash theme={"system"}
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.

<h2 id="choose-a-model-provider">
  Choisir un fournisseur de modèle
</h2>

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

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

Nous vous recommandons [Serverless Inference](/fr/products/inference/serverless) pour ce guide pas à pas. L’exemple utilise `zai-org/GLM-5.2`. Si un autre modèle du [catalogue de modèles](/fr/products/inference/serverless/models) 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 :

```bash theme={"system"}
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 :

```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 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](#run-pi-and-check-its-work) 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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md).

<h3 id="use-another-provider">
  Utiliser un autre fournisseur
</h3>

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

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

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.

<h2 id="run-pi-and-check-its-work">
  Exécuter Pi et vérifier son travail
</h2>

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 :

```text theme={"system"}
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](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/security.md).

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 :

```bash theme={"system"}
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 :

```bash theme={"system"}
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.

<h2 id="reconnect-to-a-conversation">
  Se reconnecter à une conversation
</h2>

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é :

```bash theme={"system"}
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`.

<h2 id="retrieve-the-result-and-stop">
  Récupérer le résultat et arrêter la sandbox
</h2>

Saisissez `exit` pour quitter le shell de la sandbox. Dans votre terminal local, enregistrez le code suivant sous le nom `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()
```

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 :

```bash theme={"system"}
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` :

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

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

```bash theme={"system"}
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](/fr/products/sandboxes/file-system-snapshots) dès la création.

<h2 id="troubleshoot">
  Dépannage
</h2>

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

<h2 id="next-steps">
  Étapes suivantes
</h2>

Pour plus d'informations, voir les ressources suivantes :

* [Shells interactifs](/fr/products/sandboxes/client/guides/interactive-shells) explique comment accéder au terminal via le SDK.
* [Opérations sur les fichiers](/fr/products/sandboxes/client/guides/file-operations) explique comment téléverser et récupérer les fichiers du Workspace.
* La [documentation de Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent/docs) présente les sessions, la sélection de modèle et les extensions.