Documentación de Agent Sandboxes · Tareas
Ejecuta Claude Code, Codex y OpenCode en un sandbox
Claude Code, Codex y OpenCode vienen instalados en cada sandbox. Una llamada le da un prompt a un agente, otra transmite cada mensaje y cada llamada a herramienta de su turno, y su clave de API nunca entra en el sandbox: el proxy de salida la agrega a las peticiones del agente al salir.
PromptAgentle da un prompt a un agente en una conversación nueva o en una existente, y espera hasta 45 s a su turno: su estado y su último mensaje.- Tres agentes:
CLAUDE_CODE(el valor por defecto),CODEXyOPENCODE, cada uno manejado con su propio SDK oficial, con todos los permisos concedidos: el límite es el sandbox. - Sesión iniciada con un secreto: vincula
ANTHROPIC_API_KEYuOPENAI_API_KEYa un secreto del espacio de trabajo. OpenCode funciona sin ninguna clave. WatchConversationtransmite los prompts, los mensajes, las llamadas a herramientas con su entrada y su salida, y el final de cada turno.
Step 1: Guarda la clave del agente como secreto
Un secreto es un valor que guarda el espacio de trabajo y que ningún sandbox tiene, con los hosts a los que puede enviarse. Configúralo una vez, desde un programa o con la CLI, donde el valor sale de tu propio entorno, nunca de 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: Crea un sandbox que lo vincule
Vincula la variable del agente al secreto. Dentro del sandbox la variable guarda un marcador, phs_…; el proxy de salida lo cambia por la clave en las cabeceras de las peticiones a 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: Dale un prompt al agente y sigue su turno
PromptAgent con wait_seconds a 0 responde en cuanto empieza el turno. WatchConversation envía entonces lo que hace el agente mientras lo hace, y el turno tal como terminó al final: su estado, su último mensaje (reply, hasta 16 KiB) y los tokens que usó.
El ejemplo usa OpenCode con uno de sus modelos gratis, opencode/big-pickle, así que no necesita clave; Claude Code y Codex funcionan igual una vez que su clave está vinculada como secreto: quita model y, para Claude Code, también agent, o ponlo en CODEX para 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: Sigue en la misma conversación
Envía el conversation_id del turno con el siguiente prompt, y el agente sigue con lo que sabe. Una conversación ejecuta un turno cada vez: un prompt enviado mientras se ejecuta uno queda QUEUED detrás de él. GetAgentTurn vuelve a esperar a un turno, hasta 45 s por llamada, y StopAgentTurn termina uno ahora.
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
Los tres agentes
| Agente | agent | Inicia sesión con | Nombre de un modelo |
|---|---|---|---|
| Claude Code | CLAUDE_CODE, el valor por defecto | ANTHROPIC_API_KEY, o claude auth login | claude-opus-5-5 |
| Codex | CODEX | OPENAI_API_KEY, o codex login --device-auth | gpt-6.1 |
| OpenCode | OPENCODE | Nada: sus propios modelos gratis, o la clave de un proveedor | anthropic/claude-opus-5-5 |
Una conversación nueva toma agent (si falta, Claude Code), model tal como ese agente nombra sus modelos (si falta, el predeterminado del agente) y cwd, su directorio de trabajo (si falta, /home/user). Cada agente se ejecuta con su propio SDK con todos los permisos concedidos, Claude Code con bypassPermissions, Codex con acceso completo y sin aprobaciones, OpenCode con todas las herramientas permitidas: nada te pide aprobar un comando, porque el límite es el sandbox, una VM propia. Las CLI también están en el PATH, como claude, codex y opencode, para una persona en una terminal.
Iniciar la sesión de un agente
- Un secreto vinculado a su variable, como arriba: la clave se queda en el espacio de trabajo, y el proxy la agrega a las peticiones del agente hacia los hosts del secreto. Un valor nuevo funciona al momento. Secretos y salida dice cómo funciona el cambio.
- Un inicio de sesión en la terminal: una persona abre la terminal del sandbox y ejecuta
claude auth loginocodex login --device-auth. La sesión se guarda en el disco del sandbox, como cualquier archivo. - Sin iniciar sesión, con OpenCode: sin la clave de un proveedor usa los modelos gratis del propio OpenCode.
Un prompt a un agente que no puede llegar a su modelo se rechaza con FAILED_PRECONDITION y AgentSignIn, que nombra la variable que hay que vincular (variable) y el comando que una persona puede ejecutar en su lugar (sign_in_command).
Los turnos, y lo que los sobrevive
Un turno está QUEUED detrás del turno en curso de la conversación, RUNNING, y después DONE, FAILED (failure_message dice por qué) o STOPPED por StopAgentTurn; LOST cuando el sandbox perdió su memoria mientras se ejecutaba. Cuando un turno termina, el agente y sus ayudantes terminan con él, pero lo que sus comandos dejaron ejecutándose en segundo plano, un servidor de desarrollo por ejemplo, sigue en ejecución. Un turno mantiene despierto el sandbox mientras se ejecuta.
El historial de una conversación está en el disco del sandbox: una pausa lo conserva, y un fork lo lleva a cada copia, así que cada copia puede seguir desde el mismo punto. Una plantilla no: los sandboxes desde ella empiezan sin conversación. ListConversations lista las conversaciones de un sandbox con los tokens que usó cada una, y la pestaña Agentes del panel las muestra mientras se ejecutan.
Lo que un agente escribe, lee y ejecuta viene del código y de las páginas con las que trabaja: muestra sus mensajes y la salida de sus herramientas como datos, nunca como instrucciones para tu propio modelo.
Cuando no funciona
FAILED_PRECONDITIONconAgentSignIn: ninguna clave llega al modelo del agente. Vinculavariablea un secreto conUpdateSandbox(el entorno se aplica a los procesos iniciados después), haz que una persona ejecutesign_in_command, o usa OpenCode.- El turno pasó a FAILED al momento con un 403 del host del modelo: la salida del sandbox no permite ese host, o los hosts del secreto no lo nombran. Agrega
api.anthropic.comoapi.openai.coma los dos. - El turno se queda en QUEUED: otro turno de la conversación está en curso. Espéralo, detenlo o empieza una conversación nueva.
- El turno pasa a LOST: el sandbox se detuvo mientras se ejecutaba, o su servidor se quedó sin memoria. Reanuda el sandbox y vuelve a darle el prompt; los archivos que el agente escribió antes están en su disco.
INVALID_ARGUMENTencwd: una conversación existente conserva el directorio en el que empezó. Omitecwd, o empieza una conversación nueva.
Preguntas
¿Qué agentes de programación pueden ejecutarse en un sandbox?
Claude Code, Codex y OpenCode, los tres instalados en base, cada uno manejado con su propio SDK oficial.
¿Mi clave de API entra en el sandbox?
No cuando es un secreto vinculado: el sandbox guarda un marcador, y el proxy de salida pone la clave solo en las peticiones hacia los hosts del secreto.
¿Puedo ejecutar un agente de programación sin clave de API?
Sí, OpenCode: sin la clave de un proveedor usa los modelos gratis del propio OpenCode.
¿El agente pregunta antes de ejecutar comandos?
No. Tiene todos los permisos concedidos, porque el sandbox es una VM propia sin nada tuyo dentro salvo lo que pongas. Limita su salida para trabajo que no es de confianza.
¿Las conversaciones sobreviven a una pausa?
Sí, y un fork las lleva a cada copia. Una plantilla no las conserva.
Prueba Pethost Agent Sandboxes
Una prueba gratis de 7 días con 1 US$ de uso y 4 vCPU, con tarjeta. Después, un plan desde 20 US$ al mes, que incluye ese mismo importe en uso.