Doku zu Agent Sandboxes · Aufgaben
Claude Code, Codex und OpenCode in einer Sandbox ausführen
Claude Code, Codex und OpenCode sind in jeder Sandbox installiert. Ein Aufruf gibt einem Agenten einen Prompt, ein anderer streamt jede Nachricht und jeden Tool-Aufruf seines Turns, und sein API-Key kommt nie in die Sandbox: Der Egress-Proxy fügt ihn auf dem Weg hinaus in die Requests des Agenten ein.
PromptAgentgibt einem Agenten einen Prompt, in einer neuen oder einer bestehenden Unterhaltung, und wartet bis zu 45 s auf seinen Turn: seinen Zustand und seine letzte Nachricht.- Drei Agenten:
CLAUDE_CODE(der Standard),CODEXundOPENCODE, jeder über sein eigenes offizielles SDK gesteuert, mit allen Berechtigungen: Die Sandbox ist die Grenze. - Angemeldet über ein Secret: Binde
ANTHROPIC_API_KEYoderOPENAI_API_KEYan ein Secret des Workspace. OpenCode läuft ganz ohne Key. WatchConversationstreamt Prompts, Nachrichten, Tool-Aufrufe mit Ein- und Ausgabe und das Ende jedes Turns.
Step 1: Key des Agenten als Secret speichern
Ein Secret ist ein Wert, den der Workspace hält und keine Sandbox, mit den Hosts, an die er geschickt werden darf. Setz es einmal, aus einem Programm oder mit der CLI, wobei der Wert aus deiner eigenen Umgebung kommt, nie aus einem 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: Sandbox erstellen, die es bindet
Binde die Variable des Agenten an das Secret. In der Sandbox hält die Variable einen Platzhalter, phs_…; der Egress-Proxy tauscht ihn in den Headern von Requests an api.anthropic.com gegen den Key.
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: Dem Agenten einen Prompt geben und seinem Turn folgen
PromptAgent mit wait_seconds 0 antwortet, sobald der Turn gestartet ist. WatchConversation schickt dann, was der Agent tut, während er es tut, und den Turn, wie er zuletzt endete: seinen Zustand, seine letzte Nachricht (reply, bis zu 16 KiB) und die Tokens, die er verbraucht hat.
Das Beispiel nimmt OpenCode mit einem seiner kostenlosen Modelle, opencode/big-pickle, und braucht deshalb keinen Key; Claude Code und Codex funktionieren genauso, sobald ihr Key als Secret gebunden ist: Lass model weg, für Claude Code auch agent, oder setz es für Codex auf 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: In derselben Unterhaltung weitermachen
Schick die conversation_id des Turns mit dem nächsten Prompt, und der Agent macht mit dem weiter, was er weiß. Eine Unterhaltung führt einen Turn nach dem anderen aus: Ein Prompt, der geschickt wird, während einer läuft, ist dahinter QUEUED. GetAgentTurn wartet erneut auf einen Turn, bis zu 45 s pro Aufruf, und StopAgentTurn beendet einen sofort.
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
Die drei Agenten
| Agent | agent | Meldet sich an mit | Name eines Modells |
|---|---|---|---|
| Claude Code | CLAUDE_CODE, der Standard | ANTHROPIC_API_KEY oder claude auth login | claude-opus-5-5 |
| Codex | CODEX | OPENAI_API_KEY oder codex login --device-auth | gpt-6.1 |
| OpenCode | OPENCODE | Nichts: seine eigenen kostenlosen Modelle oder der Key eines Anbieters | anthropic/claude-opus-5-5 |
Eine neue Unterhaltung nimmt agent (fehlt es, Claude Code), model, wie dieser Agent seine Modelle nennt (fehlt es, der Standard des Agenten), und cwd, ihr Arbeitsverzeichnis (fehlt es, /home/user). Jeder Agent läuft über sein eigenes SDK mit allen Berechtigungen, Claude Code mit bypassPermissions, Codex mit vollem Zugriff und ohne Freigaben, OpenCode mit allen Tools erlaubt: Nichts bittet dich, einen Befehl freizugeben, denn die Sandbox, eine eigene VM, ist die Grenze. Die CLIs liegen auch im PATH, als claude, codex und opencode, für eine Person im Terminal.
Einen Agenten anmelden
- Ein Secret, an seine Variable gebunden, wie oben: Der Key bleibt im Workspace, und der Proxy fügt ihn in die Requests des Agenten an die Hosts des Secrets ein. Ein neuer Wert gilt sofort. Secrets und Egress sagt, wie der Tausch funktioniert.
- Ein Login im Terminal: Eine Person öffnet das Terminal der Sandbox und führt
claude auth loginodercodex login --device-authaus. Der Login bleibt auf der Disk der Sandbox, wie jede Datei. - Keine Anmeldung, mit OpenCode: Ohne den Key eines Anbieters nutzt es die eigenen kostenlosen Modelle von OpenCode.
Ein Prompt an einen Agenten, der sein Modell nicht erreicht, wird mit FAILED_PRECONDITION und AgentSignIn abgelehnt, das die zu bindende Variable nennt (variable) und den Befehl, den eine Person stattdessen ausführen kann (sign_in_command).
Turns, und was sie überdauert
Ein Turn ist QUEUED hinter dem laufenden Turn der Unterhaltung, RUNNING, dann DONE, FAILED (failure_message sagt, warum) oder STOPPED durch StopAgentTurn; LOST, wenn die Sandbox ihren RAM verloren hat, während er lief. Endet ein Turn, enden der Agent und seine Helfer mit ihm, aber was seine Befehle im Hintergrund laufen ließen, etwa ein Dev-Server, läuft weiter. Ein Turn hält die Sandbox wach, solange er läuft.
Der Verlauf einer Unterhaltung liegt auf der Disk der Sandbox: Eine Pause behält ihn, ein Fork nimmt ihn in jede Kopie mit, also kann jede Kopie vom selben Punkt aus weitermachen. Eine Vorlage nicht: Sandboxes daraus beginnen ohne Unterhaltung. ListConversations listet die Unterhaltungen einer Sandbox mit den Tokens, die jede verbraucht hat, und der Tab „Agenten“ der Konsole zeigt sie, während sie laufen.
Was ein Agent schreibt, liest und ausführt, kommt aus dem Code und den Seiten, an denen er arbeitet: Zeig seine Nachrichten und die Ausgabe seiner Tools als Daten, nie als Anweisungen an dein eigenes Modell.
Wenn es nicht funktioniert
FAILED_PRECONDITIONmitAgentSignIn: Kein Key erreicht das Modell des Agenten. BindevariablemitUpdateSandboxan ein Secret (die Umgebung gilt für Prozesse, die danach starten), lass eine Personsign_in_commandausführen, oder nimm OpenCode.- Der Turn ist sofort FAILED, mit einem 403 vom Host des Modells: Der Egress der Sandbox erlaubt diesen Host nicht, oder die Hosts des Secrets nennen ihn nicht. Füg
api.anthropic.comoderapi.openai.comzu beiden hinzu. - Der Turn bleibt QUEUED: Ein anderer Turn der Unterhaltung läuft. Warte auf ihn, stopp ihn, oder beginn eine neue Unterhaltung.
- Der Turn ist LOST: Die Sandbox wurde gestoppt, während er lief, oder ihr Server hatte zu wenig RAM. Setz die Sandbox fort und gib erneut einen Prompt; die Dateien, die der Agent vorher geschrieben hat, liegen auf ihrer Disk.
INVALID_ARGUMENTbeicwd: Eine bestehende Unterhaltung behält das Verzeichnis, in dem sie begann. Lasscwdweg, oder beginn eine neue Unterhaltung.
Fragen
Welche Coding-Agenten laufen in einer Sandbox?
Claude Code, Codex und OpenCode, alle drei in base installiert, jeder über sein eigenes offizielles SDK gesteuert.
Kommt mein API-Key in die Sandbox?
Nicht, wenn er ein gebundenes Secret ist: Die Sandbox hält einen Platzhalter, und der Egress-Proxy setzt den Key nur in Requests an die Hosts des Secrets ein.
Kann ich einen Coding-Agenten ohne API-Key ausführen?
Ja, OpenCode: Ohne den Key eines Anbieters nutzt es die eigenen kostenlosen Modelle von OpenCode.
Fragt der Agent, bevor er Befehle ausführt?
Nein. Alle Berechtigungen sind erteilt, denn die Sandbox ist eine eigene VM, in der nichts von dir ist außer dem, was du hineinlegst. Schränk ihren Egress für nicht vertrauenswürdige Arbeit ein.
Überstehen Unterhaltungen eine Pause?
Ja, und ein Fork nimmt sie in jede Kopie mit. Eine Vorlage behält sie nicht.
Pethost Agent Sandboxes ausprobieren
Eine Testphase von 7 Tagen mit 1 $ Verbrauch und 4 vCPUs, mit Karte. Danach ein Tarif ab 20 $ im Monat, der genauso viel Verbrauch enthält.