Doku zu Agent Sandboxes · Referenz
Fehler der Sandboxes-API, und was zu tun ist
Was jede Ablehnung der API bedeutet und was als Nächstes zu tun ist, nach ihrem Code und ihrem typisierten Detail: für die Verzweigungen eines Programms und den nächsten Schritt eines Agenten. Verzweige nach dem Code und dem Detail, nie nach der Nachricht, die ein Satz für Menschen ist und sich ändern kann.
Einen Fehler in jedem SDK lesen
Ein gescheiterter Aufruf wirft, lehnt ab oder gibt einen Fehler zurück, mit einem Code, der Nachricht der API und, wo es eins gibt, einem typisierten Detail. Python wirft pro Code eine Unterklasse von SandboxesError (AlreadyExistsError, FailedPreconditionError…) mit dem Detail in detail; TypeScript lehnt mit einem SandboxesError ab, dessen Detail ein eigenes Feld ist (error.nameTaken); Go gibt einen *sandboxes.Error mit einem Feld pro Detail zurück; der Error von Rust hat code() und details(). Hier nimmt ein schon vergebener Name die Sandbox, die ihn hat, und eine gestoppte Sandbox wird fortgesetzt:
from pethost.sandboxes import AlreadyExistsError, FailedPreconditionError, NameTaken, Stopped
try:
sandbox = sandboxes.create_sandbox("base", name="api-dev")
except AlreadyExistsError as error:
if not isinstance(error.detail, NameTaken):
raise
sandbox = sandboxes.get_sandbox(error.detail.sandbox_id) # the sandbox that has the name
try:
command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
except FailedPreconditionError as error:
if not isinstance(error.detail, Stopped):
raise
sandboxes.resume_sandbox(sandbox.sandbox_id)
command = sandboxes.run_command(sandbox.sandbox_id, command="make test")
const created = await sandboxes.createSandbox({ template: "base", name: "api-dev" }).catch(async (error) => {
if (!(error instanceof SandboxesError) || !error.nameTaken) throw error;
return sandboxes.getSandbox({ sandboxId: error.nameTaken.sandboxId }); // the sandbox that has the name
});
const test = { sandboxId: created.sandboxId, command: "make test" };
const command = await sandboxes.runCommand(test).catch(async (error) => {
if (!(error instanceof SandboxesError) || !error.stopped) throw error;
await sandboxes.resumeSandbox({ sandboxId: created.sandboxId });
return sandboxes.runCommand(test);
});
created, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Name: "api-dev"})
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.NameTaken != nil {
created, err = client.GetSandbox(ctx, &sandboxes.GetSandboxRequest{SandboxID: e.NameTaken.SandboxID})
}
if err != nil {
log.Fatal(err)
}
test := &sandboxes.RunCommandRequest{SandboxID: created.SandboxID, Command: "make test"}
command, err := client.RunCommand(ctx, test)
if e, ok := errors.AsType[*sandboxes.Error](err); ok && e.Stopped != nil {
if _, err = client.ResumeSandbox(ctx, &sandboxes.ResumeSandboxRequest{SandboxID: created.SandboxID}); err == nil {
command, err = client.RunCommand(ctx, test)
}
}
if err != nil {
log.Fatal(err)
}
fmt.Println(command.State)
use pethost::sandboxes::ErrorDetail;
let request = CreateSandboxRequest { template: "base".into(), name: "api-dev".into(), ..Default::default() };
let created = match sandboxes.create_sandbox(request).await {
Ok(sandbox) => sandbox,
Err(error) => match error.details().iter().find_map(|detail| match detail {
ErrorDetail::NameTaken(taken) => Some(taken.sandbox_id.clone()),
_ => None,
}) {
Some(sandbox_id) => sandboxes.get_sandbox(GetSandboxRequest { sandbox_id, ..Default::default() }).await?,
None => return Err(error.into()),
},
};
let test = RunCommandRequest { sandbox_id: created.sandbox_id.clone(), command: "make test".into(), ..Default::default() };
let command = match sandboxes.run_command(test.clone()).await {
Err(error) if error.details().iter().any(|detail| matches!(detail, ErrorDetail::Stopped(_))) => {
let resume = ResumeSandboxRequest { sandbox_id: created.sandbox_id.clone(), ..Default::default() };
sandboxes.resume_sandbox(resume).await?;
sandboxes.run_command(test).await?
}
other => other?,
};
println!("{:?}", command.state);
Ablehnungen mit typisiertem Detail
| Code und Detail | Was es bedeutet | Was zu tun ist |
|---|---|---|
FAILED_PRECONDITION + Stopped | Ein Aufruf in eine STOPPED-Sandbox, ein SSH-Login oder ein Port-Request, und ihr Lebenszyklus sagt nicht wake_when_stopped. | ResumeSandbox, dann den Aufruf wiederholen. |
UNAVAILABLE + Restoring | Die Disk wird für den Start aus dem Objektspeicher geholt; bisher fetched_bytes von total_bytes, etwa 10 s pro GiB. | Warten, dann wiederholen. |
UNAVAILABLE + NoCapacity | Kein Server hat gerade Platz dafür; bound sagt, was dem letzten fehlte, und bei einem Fork fork_count, wie viele Kopien passen. | Später noch einmal versuchen, oder fork_count Kopien oder weniger forken. |
RESOURCE_EXHAUSTED + LimitReached | Ein Limit des Tarifs, genannt von limit mit seinem max: vcpus, largest_size, volume_gib, template_versions, template_gib oder secrets. | Lösch oder stopp, was es belegt, oder wähl einen größeren Tarif. Laufende und pausierte Sandboxes belegen vCPUs. |
RESOURCE_EXHAUSTED + LimitReached, starts_per_minute, _hour, _day | Zu viele Starts in diesem gleitenden Zeitfenster: Erstellungen, Kopien von Forks und Starts gestoppter Sandboxes. Starts sind kostenlos und begrenzt. | Zur retry_time wiederholen. Ohne eine verlangt der Aufruf mehr, als das Zeitfenster erlaubt: Teil ihn auf. |
FAILED_PRECONDITION + UsageUnpaid | Gerade bezahlt nichts den Workspace: Sein enthaltener Verbrauch ist aufgebraucht und sein Guthaben leer. Laufende und pausierte Sandboxes wurden gestoppt. | Wer den Workspace besitzt, lädt das Guthaben auf oder startet den Tarif aus der Testphase heraus, in der Konsole. Die Sperre fällt in Sekunden. |
FAILED_PRECONDITION + AgentSignIn | Ein Coding-Agent erreicht sein Modell nicht: variable nennt die zu bindende Variable, sign_in_command den Befehl, der stattdessen auszuführen ist. | Binde ein Secret an variable, lass eine Person sign_in_command im Terminal ausführen, oder nimm OpenCode. |
FAILED_PRECONDITION + WorkspaceChoice | Der Aufruf nennt keinen Workspace, und das Token erreicht mehrere; workspaces listet sie. | Schick workspace, seine ID oder seinen Namen, im Aufruf oder im Client. |
ALREADY_EXISTS + NameTaken | Eine andere, nicht gelöschte Sandbox des Workspace hat den Namen; sandbox_id ist diese Sandbox. | Nimm diese Sandbox, oder wähl einen anderen Namen. |
Ablehnungen nur mit Code
| Code | Was es bedeutet | Was zu tun ist |
|---|---|---|
INVALID_ARGUMENT | Ein Feld ist falsch, und die Nachricht nennt es und sagt, was es nimmt; oder eine request_id kam erneut mit anderen Feldern. | Korrigier das Feld. Nicht unverändert wiederholen. |
NOT_FOUND | Keine solche Sandbox, Vorlage, kein solches Volume oder Secret, oder keins, das das Token erreicht. Vom Server einer Sandbox: Die Sandbox ist auf einen anderen umgezogen. | Prüf die ID. Die SDKs verbinden sich selbst neu, wenn eine Sandbox umgezogen ist. |
FAILED_PRECONDITION | Der Zustand erlaubt den Aufruf nicht, wie der Aufruf sagt: eine neue Größe für eine PAUSED-Sandbox, ein noch gebundenes Secret, ein noch gemountetes Volume, eine Vorlage, die noch gespeichert wird, ein Desktop, der nicht gestartet ist. | Tu zuerst, was die Nachricht sagt, dann wiederhole. |
ABORTED | Die Einstellungen der Sandbox haben sich geändert, seit du sie gelesen hast (if_revision). | Lies sie neu und mach deine Änderung noch einmal. |
RESOURCE_EXHAUSTED | Ohne LimitReached: Die Sandbox bedient schon 64 Aufrufe gleichzeitig, oder eine Nachricht lag über ihrer Grenze (1 MiB pro Request, 17 MiB pro WriteFiles). | Beende einen Aufruf oder warte; bewege eine große Datei über einen Link. |
UNAVAILABLE | Ohne Detail: Gerade antwortet kein Server, oder die Sandbox zieht auf einen anderen Server um. | Gleich wiederholen. |
PERMISSION_DENIED | Das API-Token hat keinen Zugriff auf den Workspace, oder ein Token, das für den MCP-Server von Agent Sandboxes bestätigt wurde, hat eine andere API aufgerufen. Vom Server einer Sandbox: ein Token für einen anderen Server, nach einem Umzug. | Gib dem Token in den Einstellungen Zugriff auf den Workspace. Die SDKs verbinden sich nach einem Umzug selbst neu. |
UNAUTHENTICATED | Das Token fehlt, ist vertippt, abgelaufen oder gelöscht. Vom Server einer Sandbox: ein Verbindungs-Token, das abgelaufen ist oder widerrufen wurde (revoke_tokens). | Prüf PETHOST_TOKEN. Die SDKs holen selbst ein neues Verbindungs-Token. |
Ein Runtime-Aufruf, den der Server einer Sandbox mit UNAUTHENTICATED, PERMISSION_DENIED oder NOT_FOUND abgelehnt hat, hat nichts getan. Die SDKs und die CLI fragen ConnectSandbox einmal neu und wiederholen ihn; ein eigenes Programm über HTTP tut dasselbe.
Antworten, die sagen, dass etwas scheiterte
Manche Aufrufe gelingen und sagen in ihrer Antwort, dass ein Teil der Arbeit scheiterte: Der Aufruf hat getan, was er konnte, und die Antwort sagt, wo er aufgehört hat.
| Antwort | Werte | Was zu tun ist |
|---|---|---|
WriteFilesResponse.failure | NOT_FOUND, PERMISSION_DENIED, NOT_A_DIRECTORY, IS_A_DIRECTORY, NO_SPACE, EDIT_NOT_FOUND, EDIT_AMBIGUOUS | done_count Änderungen wurden gemacht; korrigier die nächste und schick den Rest. |
ControlDesktopResponse.failure | OFF_SCREEN, UNKNOWN_KEY | done_count Aktionen wurden erledigt; der Screenshot zeigt den Bildschirm danach. |
Command.state | TIMED_OUT, STOPPED, LOST | LOST: Die Sandbox hat ihren RAM verloren, während er lief; führ ihn noch einmal aus. |
AgentTurn.state | FAILED, STOPPED, LOST | FAILED: failure_message sagt, warum. LOST: erneut einen Prompt geben. |
Sandbox.state_reason | CRASH, UNPAID, IDLE, MAINTENANCE | CRASH: state_message sagt, warum; nur ResumeSandbox startet sie. |
Über MCP ist ein WriteFiles oder ControlDesktop, das vorzeitig aufgehört hat, ein Tool-Fehler, sein JSON so, wie die API antwortet.
An einem Port, an einem Link und über SSH
| Antwort | Was es bedeutet | Was zu tun ist |
|---|---|---|
| 401 von einem Port | Ein privater Port, und der Request hatte kein Pethost-Token, ein abgelaufenes oder das eines anderen Ports. | Mach den Port öffentlich, oder schick ein frisches Token von CreateLink. |
| 503 „stopped: resume it“ | Die Sandbox ist gestoppt und wacht durch einen Request nicht auf. SSH sagt dieselben Worte. | ResumeSandbox, oder schalt wake_when_stopped ein. |
| 503 beim Wiederherstellen | Die Disk kommt aus dem Objektspeicher zurück. | Warten, dann wiederholen. |
| 403 vom Egress-Proxy | In der Sandbox: Der Egress erlaubt den Host oder Port nicht, und die Antwort sagt, was abgelehnt hat. | Füg den Host zu egress.allow hinzu. |
| 421 Misdirected Request | In der Sandbox: ein einfacher HTTP-Request für einen anderen Host als den, zu dem seine Verbindung geöffnet wurde. | Nichts: Der Client öffnet eine neue Verbindung für diesen Host. |
Sicher wiederholen
Ein Aufruf, der etwas erstellt, nimmt eine request_id: CreateSandbox, ForkSandbox, CreateTemplate, CreateVolume, RunCommand und PromptAgent. Schick nach einem Timeout oder einer verlorenen Antwort dieselbe ID noch einmal, und die Wiederholung antwortet 24 Stunden lang mit dem, was der erste Aufruf getan hat. Die anderen Aufrufe, die etwas ändern, sind von sich aus idempotent: Eine Pause einer pausierten Sandbox, ein Löschen einer gelöschten antworten mit ihr, wie sie ist. Eine Einschränkung: Eine Sandbox hält die IDs ihrer Befehle und Turns auf ihrer Disk, also hat eine, die ihren RAM verloren hat, die ihrer letzten Sekunden vielleicht verloren, und eine Wiederholung eines solchen Befehls führt ihn noch einmal aus.
Fragen
Was bedeutet „stopped: resume it“?
Die Sandbox ist gestoppt, und ihr Lebenszyklus weckt sie bei einem Aufruf nicht. ResumeSandbox startet sie, ihre Dateien, wie sie sie verlassen hat.
Warum wird meine Sandbox mit LimitReached abgelehnt?
Der Workspace hat ein Limit seines Tarifs erreicht, das limit nennt: meist vcpus, belegt von laufenden und pausierten Sandboxes, oder ein Zeitfenster für Starts, mit retry_time.
Soll ich UNAVAILABLE wiederholen?
Ja, nach einem Moment. Mit NoCapacity etwas später; mit Restoring, sobald die Disk zurück ist.
Kann ich die Fehlermeldung parsen?
Nein: Verzweige nach dem Code und dem typisierten Detail. Die Nachricht ist ein Satz für Menschen und kann sich ändern.
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.