Documentation Agent Sandboxes · Tâches
Faire tourner Claude Code, Codex et OpenCode dans une sandbox
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.
PromptAgentdonne 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),CODEXetOPENCODE, 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_KEYouOPENAI_API_KEYà un secret de l’espace de travail. OpenCode tourne sans aucune clé. WatchConversationdiffuse 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.
import os
sandboxes.set_secret("anthropic", value=os.environ["ANTHROPIC_API_KEY"], hosts=["api.anthropic.com"])
await sandboxes.setSecret({
name: "anthropic",
value: process.env.ANTHROPIC_API_KEY!,
hosts: ["api.anthropic.com"],
});
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
Name: "anthropic",
Value: os.Getenv("ANTHROPIC_API_KEY"),
Hosts: []string{"api.anthropic.com"},
})
sandboxes
.set_secret(SetSecretRequest {
name: "anthropic".into(),
value: std::env::var("ANTHROPIC_API_KEY")?,
hosts: vec!["api.anthropic.com".into()],
..Default::default()
})
.await?;
$ 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.
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
const sandbox = await sandboxes.createSandbox({
template: "base",
name: "agent",
settings: { environment: { variables: [{ name: "ANTHROPIC_API_KEY", secret: "anthropic" }] } },
});
const sandboxId = sandbox.sandboxId;
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
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();
$ 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
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.
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
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;
}
}
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
}
}
}
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;
}
_ => {}
}
}
$ 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.
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`).
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);
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)
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);
$ 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
| Agent | agent | Se connecte avec | Un nom de modèle |
|---|---|---|---|
| Claude Code | CLAUDE_CODE, par défaut | ANTHROPIC_API_KEY, ou claude auth login | claude-opus-5-5 |
| Codex | CODEX | OPENAI_API_KEY, ou codex login --device-auth | gpt-6.1 |
| OpenCode | OPENCODE | Rien : ses propres modèles gratuits, ou la clé d’un fournisseur | anthropic/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 loginoucodex 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_PRECONDITIONavecAgentSignIn: aucune clé n’atteint le modèle de l’agent. Liezvariableà un secret avecUpdateSandbox(l’environnement s’applique aux processus lancés ensuite), faites lancersign_in_commandpar 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.comouapi.openai.comaux 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_ARGUMENTsurcwd: une conversation existante garde le dossier où elle a commencé. Omettezcwd, 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.