Français
Menu de la documentation

Documentation Agent Sandboxes · Tâches

Faire tourner Claude Code, Codex et OpenCode dans une sandbox

Mis à jour le · 10 min de lecture

Claude Code, Codex et OpenCode sont installés dans chaque sandbox. Un appel donne un prompt à un agent, un autre diffuse chaque message et chaque appel d’outil de son tour, et sa clé d’API n’entre jamais dans la sandbox : le proxy de sortie l’ajoute aux requêtes de l’agent au moment où elles sortent.

En bref
  • PromptAgent donne un prompt à un agent dans une nouvelle conversation ou une conversation existante, et attend son tour jusqu’à 45 s : son état et son dernier message.
  • Trois agents : CLAUDE_CODE (par défaut), CODEX et OPENCODE, chacun piloté par son propre SDK officiel, avec toutes les permissions accordées : c’est la sandbox qui fait la frontière.
  • Connecté par un secret : liez ANTHROPIC_API_KEY ou OPENAI_API_KEY à un secret de l’espace de travail. OpenCode tourne sans aucune clé.
  • WatchConversation diffuse les prompts, les messages, les appels d’outils avec leur entrée et leur sortie, et la fin de chaque tour.

Step 1: Enregistrez la clé de l’agent comme secret

Un secret est une valeur que l’espace de travail garde et qu’aucune sandbox ne détient, avec les hôtes auxquels elle peut être envoyée. Définissez-le une fois, depuis un programme ou avec la CLI, la valeur venant de votre propre environnement, jamais d’un prompt.

Python
import os

sandboxes.set_secret("anthropic", value=os.environ["ANTHROPIC_API_KEY"], hosts=["api.anthropic.com"])
TypeScript
await sandboxes.setSecret({
  name: "anthropic",
  value: process.env.ANTHROPIC_API_KEY!,
  hosts: ["api.anthropic.com"],
});
Go
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
	Name:  "anthropic",
	Value: os.Getenv("ANTHROPIC_API_KEY"),
	Hosts: []string{"api.anthropic.com"},
})
Rust
sandboxes
    .set_secret(SetSecretRequest {
        name: "anthropic".into(),
        value: std::env::var("ANTHROPIC_API_KEY")?,
        hosts: vec!["api.anthropic.com".into()],
        ..Default::default()
    })
    .await?;
CLI
$ printf %s "$ANTHROPIC_API_KEY" | pethost sandbox secret set anthropic --host api.anthropic.com
✓ Set the secret anthropic for api.anthropic.com. Bind it:  --env <VARIABLE>=secret:anthropic
anthropic

Step 2: Créez une sandbox qui le lie

Liez la variable de l’agent au secret. Dans la sandbox, la variable contient un marqueur, phs_… ; le proxy de sortie le remplace par la clé dans les en-têtes des requêtes vers api.anthropic.com.

Python
from pethost.sandboxes import Environment, EnvVar, SandboxSettings

sandbox = sandboxes.create_sandbox(
    "base",
    name="agent",
    settings=SandboxSettings(
        environment=Environment(variables=[EnvVar(name="ANTHROPIC_API_KEY", secret="anthropic")]),
    ),
)
sandbox_id = sandbox.sandbox_id
TypeScript
const sandbox = await sandboxes.createSandbox({
  template: "base",
  name: "agent",
  settings: { environment: { variables: [{ name: "ANTHROPIC_API_KEY", secret: "anthropic" }] } },
});
const sandboxId = sandbox.sandboxId;
Go
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{
	Template: "base",
	Name:     "agent",
	Settings: &sandboxes.SandboxSettings{Environment: &sandboxes.Environment{Variables: []sandboxes.EnvVar{
		{Name: "ANTHROPIC_API_KEY", Source: sandboxes.EnvVarSecret("anthropic")},
	}}},
})
if err != nil {
	log.Fatal(err)
}
id := sandbox.SandboxID
Rust
let key = EnvVar { name: "ANTHROPIC_API_KEY".into(), source: Some(EnvVarSource::Secret("anthropic".into())) };
let sandbox = sandboxes
    .create_sandbox(CreateSandboxRequest {
        template: "base".into(),
        name: "agent".into(),
        settings: Some(SandboxSettings {
            environment: Some(Environment { variables: vec![key] }),
            ..Default::default()
        }),
        ..Default::default()
    })
    .await?;
let id = sandbox.sandbox_id.clone();
CLI
$ pethost sandbox new --name agent --env ANTHROPIC_API_KEY=secret:anthropic
✓ Made sandbox agent (kjxa3j9hvg9qmmqe): default, running, from base@17, in <1 s
kjxa3j9hvg9qmmqe
Next:   pethost sandbox run kjxa3j9hvg9qmmqe -- <command>   ·   pethost sandbox shell kjxa3j9hvg9qmmqe
MCP
CreateSandbox {"name": "agent", "settings": {"environment": {"variables": [{"name": "ANTHROPIC_API_KEY", "secret": "anthropic"}]}}}

Step 3: Donnez un prompt à l’agent et suivez son tour

PromptAgent avec wait_seconds à 0 répond une fois le tour commencé. WatchConversation envoie ensuite ce que fait l’agent au moment où il le fait, puis le tour tel qu’il s’est terminé : son état, son dernier message (reply, jusqu’à 16 KiB) et les tokens qu’il a consommés.

L’exemple utilise OpenCode avec l’un de ses modèles gratuits, opencode/big-pickle, et n’a donc besoin d’aucune clé ; Claude Code et Codex fonctionnent de la même façon une fois leur clé liée comme secret : retirez model, puis aussi agent pour Claude Code, ou mettez-le à CODEX pour Codex.

Python
from pethost.sandboxes import Agent

turn = sandboxes.prompt_agent(
    sandbox_id,
    prompt="Write a FizzBuzz in Python in fizz.py, with a test, and run the test.",
    agent=Agent.OPENCODE,
    model="opencode/big-pickle",
    wait_seconds=0,
)
for event in sandboxes.watch_conversation(sandbox_id, conversation_id=turn.conversation_id):
    if event.tool_call is not None:
        print("tool:", event.tool_call.name)
    elif event.message is not None:
        print("says:", event.message)
    elif event.turn_end is not None and event.turn_id == turn.turn_id:
        print(event.turn_end.state.name, event.turn_end.output_tokens, "tokens out")
        break
# tool: bash
# tool: write
# tool: write
# tool: bash
# tool: bash
# says: Created `fizz.py` and `test_fizz.py`; `python3 -m unittest test_fizz -v` passes.
# DONE 338 tokens out
TypeScript
const turn = await sandboxes.promptAgent({
  sandboxId,
  prompt: "Write a FizzBuzz in Python in fizz.py, with a test, and run the test.",
  agent: Agent.OPENCODE,
  model: "opencode/big-pickle",
  waitSeconds: 0,
});
for await (const event of sandboxes.watchConversation({ sandboxId, conversationId: turn.conversationId })) {
  if (event.event === "toolCall") console.log("tool:", event.toolCall.name);
  if (event.event === "message") console.log("says:", event.message);
  if (event.event === "turnEnd" && event.turnId === turn.turnId) {
    console.log(event.turnEnd.state, event.turnEnd.outputTokens, "tokens out");
    break;
  }
}
Go
turn, err := client.PromptAgent(ctx, &sandboxes.PromptAgentRequest{
	SandboxID:   id,
	Prompt:      "Write a FizzBuzz in Python in fizz.py, with a test, and run the test.",
	Agent:       sandboxes.AgentOpencode,
	Model:       "opencode/big-pickle",
	WaitSeconds: new(uint32(0)),
})
if err != nil {
	log.Fatal(err)
}
events := client.WatchConversation(ctx, &sandboxes.WatchConversationRequest{SandboxID: id, ConversationID: turn.ConversationID})
watch:
for event, err := range events {
	if err != nil {
		log.Fatal(err)
	}
	switch e := event.Event.(type) {
	case sandboxes.AgentEventToolCall:
		fmt.Println("tool:", e.Name)
	case sandboxes.AgentEventMessage:
		fmt.Println("says:", string(e))
	case sandboxes.AgentEventTurnEnd:
		if event.TurnID == turn.TurnID {
			fmt.Println(e.State, e.OutputTokens, "tokens out")
			break watch
		}
	}
}
Rust
let turn = sandboxes
    .prompt_agent(PromptAgentRequest {
        sandbox_id: id.clone(),
        prompt: "Write a FizzBuzz in Python in fizz.py, with a test, and run the test.".into(),
        agent: Agent::Opencode,
        model: "opencode/big-pickle".into(),
        wait_seconds: Some(0),
        ..Default::default()
    })
    .await?;
let mut events = sandboxes.watch_conversation(WatchConversationRequest {
    sandbox_id: id.clone(),
    conversation_id: turn.conversation_id.clone(),
    ..Default::default()
});
while let Some(event) = events.next().await {
    let event = event?;
    match event.event {
        Some(AgentEventEvent::ToolCall(call)) => println!("tool: {}", call.name),
        Some(AgentEventEvent::Message(text)) => println!("says: {text}"),
        Some(AgentEventEvent::TurnEnd(end)) if event.turn_id == turn.turn_id => {
            println!("{:?} {} tokens out", end.state, end.output_tokens);
            break;
        }
        _ => {}
    }
}
CLI
$ pethost sandbox agent agent --agent opencode --model opencode/big-pickle 'Write a FizzBuzz in Python in fizz.py, with a test, and run the test.'
opencode · conversation dk5p1kaxc1mj
› bash: ls -la /home/user
› write: def fizzbuzz(n): if n % 15 == 0: return "FizzBuzz" if n % 3 == 0: return "Fizz" if n % 5 == 0: retur…
› write: import unittest from fizz import fizzbuzz, fizzbuzz_sequence class FizzBuzzTest(unittest.TestCase): …
› bash: python3 -m unittest -v test_fizz.py
Running the test with Python's standard `unittest` runner.
Created `fizz.py` and `test_fizz.py`. Tests passed: 2/2 via `python3 -m unittest -v test_fizz.py`.
done · opencode · conversation dk5p1kaxc1mj · 33k tokens in, 1.1k out

Step 4: Continuez dans la même conversation

Envoyez le conversation_id du tour avec le prompt suivant, et l’agent reprend avec ce qu’il sait. Une conversation fait un tour à la fois : un prompt envoyé pendant qu’un tour tourne est QUEUED derrière lui. GetAgentTurn attend de nouveau un tour, jusqu’à 45 s par appel, et StopAgentTurn en termine un tout de suite.

Python
from pethost.sandboxes import AgentTurnState

next_turn = sandboxes.prompt_agent(sandbox_id, prompt="Now make it read n from argv.", conversation_id=turn.conversation_id)
while next_turn.state in (AgentTurnState.QUEUED, AgentTurnState.RUNNING):
    next_turn = sandboxes.get_agent_turn(sandbox_id, turn_id=next_turn.turn_id)
print(next_turn.state.name, next_turn.reply)
# DONE `fizz.py` now reads `n` from `sys.argv[1]`; tests pass and CLI works (`python3 fizz.py 15` → `FizzBuzz`).
TypeScript
let nextTurn = await sandboxes.promptAgent({
  sandboxId,
  prompt: "Now make it read n from argv.",
  conversationId: turn.conversationId,
});
while (nextTurn.state === AgentTurnState.QUEUED || nextTurn.state === AgentTurnState.RUNNING) {
  nextTurn = await sandboxes.getAgentTurn({ sandboxId, turnId: nextTurn.turnId });
}
console.log(nextTurn.state, nextTurn.reply);
Go
next, err := client.PromptAgent(ctx, &sandboxes.PromptAgentRequest{
	SandboxID:      id,
	Prompt:         "Now make it read n from argv.",
	ConversationID: turn.ConversationID,
})
for err == nil && (next.State == sandboxes.AgentTurnStateQueued || next.State == sandboxes.AgentTurnStateRunning) {
	next, err = client.GetAgentTurn(ctx, &sandboxes.GetAgentTurnRequest{SandboxID: id, TurnID: next.TurnID})
}
if err != nil {
	log.Fatal(err)
}
fmt.Println(next.State, next.Reply)
Rust
let mut next = sandboxes
    .prompt_agent(PromptAgentRequest {
        sandbox_id: id.clone(),
        prompt: "Now make it read n from argv.".into(),
        conversation_id: turn.conversation_id.clone(),
        ..Default::default()
    })
    .await?;
while matches!(next.state, AgentTurnState::Queued | AgentTurnState::Running) {
    let ask = GetAgentTurnRequest { sandbox_id: id.clone(), turn_id: next.turn_id.clone(), ..Default::default() };
    next = sandboxes.get_agent_turn(ask).await?;
}
println!("{:?} {}", next.state, next.reply);
CLI
$ pethost sandbox agent agent --conversation dk5p1kaxc1mj 'Now make it read n from argv.'
opencode · conversation dk5p1kaxc1mj
› read: /home/user/fizz.py
› read: /home/user/test_fizz.py
› edit: /home/user/fizz.py
› edit: /home/user/fizz.py
› edit: /home/user/test_fizz.py
› edit: /home/user/test_fizz.py
› bash: python3 -m unittest -v test_fizz.py
› bash: python3 fizz.py 5
`fizz.py` now reads `N` from argv via `main()` (fizz.py:19). `python3 fizz.py 5` prints `1, 2, Fizz, 4, Buzz`. Tests: 3/3 passed.
done · opencode · conversation dk5p1kaxc1mj · 61.4k tokens in, 1.6k out

Les trois agents

AgentagentSe connecte avecUn nom de modèle
Claude CodeCLAUDE_CODE, par défautANTHROPIC_API_KEY, ou claude auth loginclaude-opus-5-5
CodexCODEXOPENAI_API_KEY, ou codex login --device-authgpt-6.1
OpenCodeOPENCODERien : ses propres modèles gratuits, ou la clé d’un fournisseuranthropic/claude-opus-5-5

Une nouvelle conversation prend agent (absent, c’est Claude Code), model tel que cet agent nomme ses modèles (absent, c’est le modèle par défaut de l’agent) et cwd, son dossier de travail (absent, c’est /home/user). Chaque agent tourne par son propre SDK avec toutes les permissions accordées, Claude Code avec bypassPermissions, Codex avec un accès complet et sans approbations, OpenCode avec tous les outils autorisés : rien ne vous demande d’approuver une commande, parce que la sandbox, une VM à elle, fait la frontière. Les CLI sont aussi dans le PATH, sous les noms claude, codex et opencode, pour une personne dans un terminal.

Connecter un agent

  • Un secret lié à sa variable, comme ci-dessus : la clé reste dans l’espace de travail, et le proxy l’ajoute aux requêtes de l’agent vers les hôtes du secret. Une nouvelle valeur marche aussitôt. Secrets et trafic sortant dit comment marche la substitution.
  • Une connexion dans le terminal : une personne ouvre le terminal de la sandbox et lance claude auth login ou codex login --device-auth. La connexion est gardée sur le disque de la sandbox, comme n’importe quel fichier.
  • Aucune connexion, avec OpenCode : sans clé de fournisseur, il utilise les modèles gratuits d’OpenCode.

Un prompt à un agent qui ne peut pas joindre son modèle est refusé avec FAILED_PRECONDITION et AgentSignIn, qui nomme la variable à lier (variable) et la commande qu’une personne peut lancer à la place (sign_in_command).

Les tours, et ce qui leur survit

Un tour est QUEUED derrière le tour en cours de la conversation, puis RUNNING, puis DONE, FAILED (failure_message dit pourquoi) ou STOPPED par StopAgentTurn ; LOST quand la sandbox a perdu sa mémoire pendant qu’il tournait. Quand un tour se termine, l’agent et ses auxiliaires se terminent avec lui, mais ce que ses commandes ont laissé tourner en arrière-plan, un serveur de développement par exemple, continue. Un tour garde la sandbox éveillée tant qu’il tourne.

L’historique d’une conversation est sur le disque de la sandbox : une pause le garde, une duplication l’emporte dans chaque copie, et chaque copie peut donc reprendre au même point. Un template, non : les sandboxes qui en sont issues démarrent sans conversation. ListConversations liste les conversations d’une sandbox avec les tokens que chacune a consommés, et l’onglet Agents de la console les montre pendant qu’elles tournent.

Ce qu’un agent écrit, lit et exécute vient du code et des pages sur lesquels il travaille : montrez ses messages et la sortie de ses outils comme des données, jamais comme des instructions pour votre propre modèle.

Quand ça ne marche pas

  • FAILED_PRECONDITION avec AgentSignIn : aucune clé n’atteint le modèle de l’agent. Liez variable à un secret avec UpdateSandbox (l’environnement s’applique aux processus lancés ensuite), faites lancer sign_in_command par une personne, ou utilisez OpenCode.
  • Le tour est FAILED tout de suite avec un 403 de l’hôte du modèle : le trafic sortant de la sandbox n’autorise pas cet hôte, ou les hôtes du secret ne le nomment pas. Ajoutez api.anthropic.com ou api.openai.com aux deux.
  • Le tour reste QUEUED : un autre tour de la conversation est en cours. Attendez-le, arrêtez-le, ou commencez une nouvelle conversation.
  • Le tour est LOST : la sandbox s’est arrêtée pendant qu’il tournait, ou son serveur a manqué de mémoire. Reprenez la sandbox et redonnez le prompt ; les fichiers que l’agent a écrits avant sont sur son disque.
  • INVALID_ARGUMENT sur cwd : une conversation existante garde le dossier où elle a commencé. Omettez cwd, ou commencez une nouvelle conversation.

Questions

Quels agents de code peuvent tourner dans une sandbox ?

Claude Code, Codex et OpenCode, tous trois installés dans base, chacun piloté par son propre SDK officiel.

Ma clé d’API entre-t-elle dans la sandbox ?

Pas quand c’est un secret lié : la sandbox détient un marqueur, et le proxy de sortie met la clé dans les requêtes vers les hôtes du secret seulement.

Puis-je faire tourner un agent de code sans clé d’API ?

Oui, OpenCode : sans clé de fournisseur, il utilise les modèles gratuits d’OpenCode.

L’agent demande-t-il avant de lancer des commandes ?

Non. Toutes les permissions sont accordées, parce que la sandbox est une VM à elle, sans rien de vous à l’intérieur que ce que vous y mettez. Restreignez son trafic sortant pour un travail non fiable.

Les conversations survivent-elles à une pause ?

Oui, et une duplication les emporte dans chaque copie. Un template ne les garde pas.

Essayez Pethost Agent Sandboxes

Un essai gratuit de 7 jours avec 1 $ de consommation et 4 vCPU, avec une carte. Ensuite, une offre dès 20 $ par mois, qui inclut autant de consommation.

Démarrer l’essai gratuit