Deutsch
Menü der Doku

Doku zu Agent Sandboxes · Einstieg

Einen Agenten über MCP mit Sandboxes verbinden

Aktualisiert · 6 Min. Lesezeit

Sandboxes als Tools deines Agenten: Füg den MCP-Server von Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, zu Claude Code, Codex, Cursor oder Claude hinzu, melde dich in deinem Browser an, und der Agent erstellt, forkt, pausiert und löscht Sandboxes selbst.

Kurz gesagt
  • Eine Adresse: https://mcp.pethost.dev/sandboxes, Streamable HTTP, Anmeldung per OAuth. Kein Key zum Einfügen.
  • Du wählst den Workspace: Die Anmeldeseite bietet deine Workspaces für Sandboxes an, und das Token des Agenten erreicht nur die, die du auswählst.
  • 13 Tools für den Workspace und den Eintrag jeder Sandbox. Befehle und Dateien gehen an den eigenen Server der Sandbox, den der Agent mit ConnectSandbox und der pethost-CLI oder curl erreicht.
  • Getrennt von App Platform: ein eigener Connector, also sieht ein Agent, der für das eine eingerichtet ist, nie die Tools des anderen.

Step 1: Server zu Claude Code hinzufügen

claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes

Oder installier das Plugin, das den Server mitbringt und einen Skill, der Claude sagt, wann und wie es Sandboxes nutzt: claude plugin marketplace add pethost-dev/plugin, dann claude plugin install pethost-sandboxes@pethost.

Step 2: Anmelden

Führ in Claude Code /mcp aus, wähl pethost-sandboxes und authentifiziere dich. Dein Browser öffnet die Bestätigungsseite von Pethost: Melde dich an, wähl den Workspace für Sandboxes, den der Agent nutzen darf, und drück Verbinden.

Step 3: Um etwas bitten, das einen Computer braucht

„Erstell eine Sandbox, klon dieses Repository und führ seine Tests aus.“ Der Agent liest den Workspace, erstellt eine Sandbox aus base und arbeitet darin.

Claude Code

Du sagst: Erstell eine Sandbox, klon https://github.com/pallets/click und führ seine Tests aus.

  • CreateSandbox {"name": "click-tests"}
  • ConnectSandbox {"sandbox_id": "lelb0x9iq6pvk7t8", "ttl_seconds": 3600}
  • Bash curl …/SandboxRuntimeService/RunCommand: git clone -q https://github.com/pallets/click
  • Bash curl …/SandboxRuntimeService/RunCommand: python3 -m venv .venv && .venv/bin/pip install -q -e . pytest && .venv/bin/python -m pytest -q

Der Agent antwortet: Alle Tests von click sind in einer neuen Sandbox durchgelaufen: 2628 passed, 24 skipped, 1 xfailed, 0 failed (pytest-Exit-Code 0). … Die Sandbox pausiert nach 5 min Leerlauf und stoppt nach 30, wird aber nicht automatisch gelöscht. Soll ich sie löschen oder für weitere Arbeit behalten?

Codex

Das Plugin, für die CLI und die Desktop-App, bringt den Server und den Skill mit: codex plugin marketplace add pethost-dev/plugin, dann codex plugin add pethost-sandboxes@pethost. Du meldest dich in deinem Browser an, wie bei Claude Code, und wählst dort den Workspace.

Cursor

Füg den Server zu ~/.cursor/mcp.json hinzu, oder zu .cursor/mcp.json in einem Projekt, und schalt ihn dann in den MCP-Einstellungen von Cursor ein, die die Anmeldung starten:

{
  "mcpServers": {
    "pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
  }
}

Claude im Web und auf dem Desktop

Öffne in den Einstellungen von Claude die Connectors, füg einen eigenen Connector hinzu und gib ihm die Adresse https://mcp.pethost.dev/sandboxes. Claude öffnet die Anmeldeseite; dann schalt den Connector in einer Unterhaltung ein.

Jeder andere Agent

Jeder MCP-Client, der Streamable HTTP spricht und sich per OAuth anmeldet, nimmt die Adresse https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. Der Skill, für einen Agenten, der Skills liest: npx skills add pethost-dev/plugin --skill pethost-sandboxes. Ein Agent, der nur den Server bekommt, liest stattdessen dessen Anweisungen, die sagen, wo er anfängt.

Die Tools

Die Tools des Servers sind die Aufrufe von SandboxService, der Hälfte der API beim Panel, jeder mit demselben Namen, denselben Feldern und Antworten wie in der API-Referenz:

ToolWas es tut
GetWorkspaceDie Limits, Größen und Preise des Workspace, die Namen seiner Secrets und seine SSH-Keys.
ListSandboxesSeine Sandboxes, die neueste zuerst, nach Zustand, Label oder Name.
CreateSandboxEine Sandbox aus einer Vorlage, beantwortet, sobald sie läuft.
GetSandboxEine Sandbox: ihr Zustand und warum, ihre Einstellungen, wie man sie erreicht, ihr Verbrauch.
UpdateSandboxName, Größe, Lebenszyklus, Egress, öffentliche Ports oder Umgebung der Sandbox.
PauseSandboxSie pausieren, RAM und Prozesse bleiben.
StopSandboxSie stoppen, ihre Disk bleibt.
ResumeSandboxEine pausierte oder gestoppte wieder starten.
ForkSandboxSie kopieren, RAM und Prozesse eingeschlossen, in neue Sandboxes.
DeleteSandboxSie löschen, RAM und Disk endgültig.
ConnectSandboxDer Server der Sandbox, ein Token dafür und ihr SSH-Befehl.
CreateTemplateDie Disk einer Sandbox als Vorlage speichern.
ListTemplatesUnsere Vorlagen und die des Workspace.

Befehle und Dateien: beim eigenen Server der Sandbox

Was in einer Sandbox läuft, ihre Befehle, Dateien, ihr Desktop, ihre Links und Coding-Agenten, beantwortet der Server, auf dem die Sandbox läuft, nie das Panel. Darum listet der MCP-Server unter mcp.pethost.dev/sandboxes kein RunCommand: Der Agent ruft ConnectSandbox auf, das die url des Servers, ein token für diese eine Sandbox und ihr ssh_command zurückgibt, und arbeitet dann selbst dort:

  • Mit der pethost-CLI, wo der Agent eine Shell hat: pethost sandbox run <id> -- npm test, pethost sandbox cp ./app <id>:app, pethost sandbox shell <id>.
  • Mit curl, jeder Aufruf von SandboxRuntimeService über seinen Namen, in Connect-JSON mit den Feldnamen, die die Tools verwenden.
  • Ohne Shell gibt dir der Agent die panel_url der Sandbox, wo ihr Terminal und ihr Desktop sind, sobald du dich anmeldest.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'

Das Token ist root in dieser Sandbox: Die Anweisungen des Servers und der Skill sagen dem Agenten, es in einer Shell-Variablen zu halten und nie in der Unterhaltung auszugeben.

Ein Token nur für diesen Server

Die Anmeldung gibt dem Agenten ein Pethost-API-Token, dessen Audience dieser Server ist: Es funktioniert unter mcp.pethost.dev/sandboxes und an der API der Sandboxes und wird am MCP-Server der App Platform abgelehnt, wie das Token der App Platform hier abgelehnt wird. Es erreicht nur die Workspaces, die du ausgewählt hast. Die Einstellungen deines Kontos listen es unter dem Namen des Agenten, mit dem, was es erreicht, und löschen es.

Warum es ein eigener Connector ist

App Platform und Agent Sandboxes sind zwei Produkte mit verschiedenen Tools und für verschiedene Leser gedacht: einen Agenten, der deine Apps deployt, und einen Agenten, der Computer braucht, um Code darauf auszuführen. Jedes hat seinen eigenen Server, Namen, sein Icon, seine Tools und Tokens, also liest ein Agent, der für das eine eingerichtet ist, die des anderen nie und verwechselt sie nicht. Ein Konto mit beiden fügt beide hinzu: Der der App Platform ist https://mcp.pethost.dev/mcp.

Wenn es nicht funktioniert

  • Die Anmeldeseite bietet keinen Workspace an: Sie bietet nur Workspaces für Sandboxes an. Leg zuerst einen in der Konsole an, mit Agent Sandboxes als Art.
  • Der Agent sagt, er sei nicht angemeldet, oder seine Aufrufe antworten 401: Das Token wurde gelöscht, oder der Agent hat sich beim Server der App Platform angemeldet. Melde dich aus dem Agenten neu an (/mcp in Claude Code).
  • Ein Tool antwortet WorkspaceChoice: Das Token erreicht mehrere Workspaces für Sandboxes. Sag dem Agenten, welchen; er schickt dessen workspace in jedem Aufruf.
  • Der Agent sucht RunCommand: Das ist kein Tool dieses Servers. Verweis ihn auf ConnectSandbox und die CLI, oder installier das Plugin, dessen Skill das sagt.
  • RESOURCE_EXHAUSTED mit LimitReached: Die vCPUs des Workspace sind von seinen laufenden und pausierten Sandboxes belegt. Bitte den Agenten, die zu löschen, die er nicht mehr braucht.

Fragen

Wie lautet die Adresse des MCP-Servers?

https://mcp.pethost.dev/sandboxes, Streamable HTTP, Anmeldung per OAuth in deinem Browser.

Welche Agenten funktionieren mit Pethost Agent Sandboxes?

Jeder Agent, der einen Remote-MCP-Server nimmt: Claude Code, Codex, Cursor, Claude im Web und auf dem Desktop, Hermes Agent und andere. Claude Code und Codex können das Plugin installieren, das einen Skill hinzufügt.

Kann der Agent über MCP Befehle in einer Sandbox ausführen?

Über den eigenen Server der Sandbox: ConnectSandbox gibt dessen Adresse und ein Token, und der Agent führt Befehle mit der pethost-CLI oder curl aus. Der MCP-Server selbst erstellt, ändert, pausiert, forkt und löscht Sandboxes.

Bekommt der Agent meine API-Keys?

Nein. Er bekommt ein Token für die Workspaces, die du auswählst. Keys für Modelle und Dienste sind Secrets des Workspace, die keine Sandbox und keine Antwort eines Tools je hält.

Ist es derselbe Server wie der von Pethost App Platform?

Nein: Der der App Platform ist https://mcp.pethost.dev/mcp. Jeder hat seine eigenen Tools und Tokens.

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.

Testphase starten