Dokumentacja Agent Sandboxes · Pierwsze kroki
Podłącz agenta do sandboxów przez MCP
Sandboxy jako narzędzia twojego agenta: dodaj serwer MCP Pethost Agent Sandboxes, https://mcp.pethost.dev/sandboxes, do Claude Code, Codexa, Cursora albo Claude’a, zaloguj się w przeglądarce, a agent sam tworzy sandboxy, robi ich forki, wstrzymuje je i usuwa.
- Jeden adres:
https://mcp.pethost.dev/sandboxes, streamable HTTP, logowanie przez OAuth. Żadnego klucza do wklejania. - Ty wybierasz przestrzeń roboczą: strona logowania pokazuje twoje przestrzenie robocze z sandboxami, a token agenta sięga tylko tych, które wybierzesz.
- 13 narzędzi dla przestrzeni roboczej i zapisu każdego sandboxa. Polecenia i pliki idą do serwera samego sandboxa, do którego agent dociera przez
ConnectSandboxi CLIpethostalbocurl. - Osobno od App Platform: osobny konektor, więc agent ustawiony do jednego nigdy nie widzi narzędzi drugiego.
Step 1: Dodaj serwer do Claude Code
claude mcp add --transport http pethost-sandboxes https://mcp.pethost.dev/sandboxes
Albo zainstaluj plugin, który przynosi serwer i skill mówiący Claude’owi, kiedy i jak używać sandboxów: claude plugin marketplace add pethost-dev/plugin, potem claude plugin install pethost-sandboxes@pethost.
Step 2: Zaloguj się
W Claude Code uruchom /mcp, wybierz pethost-sandboxes i się uwierzytelnij. Przeglądarka otworzy stronę zatwierdzania Pethost: zaloguj się, wybierz przestrzeń roboczą z sandboxami, której agent może używać, i naciśnij Podłącz.
Step 3: Poproś o coś, do czego potrzebny jest komputer
„Utwórz sandbox, sklonuj to repozytorium i uruchom jego testy”. Agent czyta przestrzeń roboczą, tworzy sandbox z base i w nim pracuje.
Ty mówisz: Utwórz sandbox, sklonuj https://github.com/pallets/click i uruchom jego testy.
- 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
Agent odpowiada: Wszystkie testy click przeszły w nowym sandboxie: 2628 passed, 24 skipped, 1 xfailed, 0 failed (kod wyjścia pytest 0). … Sandbox wstrzyma się po 5 minutach bezczynności i zatrzyma po 30, ale nie zostanie usunięty automatycznie. Usunąć go, czy zostawić do dalszej pracy?
Codex
Plugin, dla CLI i aplikacji desktopowej, przynosi serwer i skill: codex plugin marketplace add pethost-dev/plugin, potem codex plugin add pethost-sandboxes@pethost. Logujesz się w przeglądarce, jak w Claude Code, i tam wybierasz przestrzeń roboczą.
Cursor
Dodaj serwer do ~/.cursor/mcp.json albo do .cursor/mcp.json w projekcie, a potem włącz go w ustawieniach MCP Cursora, które rozpoczną logowanie:
{
"mcpServers": {
"pethost-sandboxes": { "url": "https://mcp.pethost.dev/sandboxes" }
}
}
Claude w przeglądarce i na desktopie
W ustawieniach Claude’a otwórz Konektory, dodaj własny konektor i podaj adres https://mcp.pethost.dev/sandboxes. Claude otworzy stronę logowania; potem włącz konektor w rozmowie.
Każdy inny agent
Każdy klient MCP, który mówi streamable HTTP i loguje się przez OAuth, przyjmie adres https://mcp.pethost.dev/sandboxes. Hermes Agent: hermes mcp add pethost-sandboxes --url https://mcp.pethost.dev/sandboxes --auth oauth. Skill, dla agenta, który czyta skille: npx skills add pethost-dev/plugin --skill pethost-sandboxes. Agent, który dostał sam serwer, czyta zamiast tego jego instrukcje, które mówią, od czego zacząć.
Narzędzia
Narzędzia serwera to wywołania SandboxService, połowy API należącej do panelu, każde z tą samą nazwą, polami i odpowiedziami co w referencji API:
| Narzędzie | Co robi |
|---|---|
GetWorkspace | Limity przestrzeni roboczej, rozmiary i ceny, nazwy jej sekretów i klucze SSH. |
ListSandboxes | Jej sandboxy, od najnowszych, według stanu, etykiety albo nazwy. |
CreateSandbox | Sandbox z szablonu, z odpowiedzią, gdy już działa. |
GetSandbox | Jeden sandbox: jego stan i powód, ustawienia, jak się do niego dostać, zużycie. |
UpdateSandbox | Jego nazwa, rozmiar, cykl życia, ruch wychodzący, publiczne porty albo środowisko. |
PauseSandbox | Wstrzymuje go, z zachowaną pamięcią i procesami. |
StopSandbox | Zatrzymuje go, z zachowanym dyskiem. |
ResumeSandbox | Ponownie uruchamia wstrzymany albo zatrzymany. |
ForkSandbox | Kopiuje go, łącznie z pamięcią i procesami, do nowych sandboxów. |
DeleteSandbox | Usuwa go, razem z pamięcią i dyskiem, na dobre. |
ConnectSandbox | Serwer sandboxa, token do niego i jego polecenie SSH. |
CreateTemplate | Zapisuje dysk sandboxa jako szablon. |
ListTemplates | Nasze szablony i te z przestrzeni roboczej. |
Polecenia i pliki: na serwerze samego sandboxa
Na to, co działa w sandboxie, czyli jego polecenia, pliki, pulpit, linki i agentów kodujących, odpowiada serwer, na którym działa sandbox, nigdy panel. Dlatego serwer MCP pod mcp.pethost.dev/sandboxes nie ma RunCommand: agent wywołuje ConnectSandbox, które zwraca url serwera, token dla tego jednego sandboxa i jego ssh_command, a potem sam tam pracuje:
- Przez CLI
pethost, gdy agent ma powłokę:pethost sandbox run <id> -- npm test,pethost sandbox cp ./app <id>:app,pethost sandbox shell <id>. - Przez
curl, dowolne wywołanieSandboxRuntimeServicepo nazwie, w JSON-ie Connect, z nazwami pól takimi jak w narzędziach. - Bez powłoki agent podaje ci
panel_urlsandboxa, gdzie po zalogowaniu są jego terminal i pulpit.
curl -s "$URL/pethost.sandboxes.v1.SandboxRuntimeService/RunCommand" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"sandbox_id": "'"$ID"'", "command": "npm test"}'
Token daje roota w tym sandboxie: instrukcje serwera i skill mówią agentowi, żeby trzymał go w zmiennej powłoki i nigdy nie wypisywał w rozmowie.
Token tylko dla tego serwera
Logowanie daje agentowi token API Pethost, którego odbiorcą jest ten serwer: działa pod mcp.pethost.dev/sandboxes i w API sandboxów, a serwer MCP App Platform go odrzuca, tak jak tutaj odrzucany jest token App Platform. Sięga tylko wybranych przez ciebie przestrzeni roboczych. Ustawienia twojego konta pokazują go pod nazwą agenta, z tym, do czego sięga, i tam go odłączysz.
Dlaczego to osobny konektor
App Platform i Agent Sandboxes to dwa produkty z różnymi narzędziami i z myślą o innym odbiorcy: agencie, który wdraża twoje aplikacje, i agencie, który potrzebuje komputerów do uruchamiania kodu. Każdy ma własny serwer, nazwę, ikonę, narzędzia i tokeny, więc agent ustawiony do jednego nigdy nie czyta narzędzi drugiego ani ich nie myli. Konto z oboma dodaje oba: serwer App Platform to https://mcp.pethost.dev/mcp.
Gdy to nie działa
- Strona logowania nie pokazuje żadnej przestrzeni roboczej: pokazuje tylko przestrzenie robocze z sandboxami. Najpierw utwórz taką w panelu, wybierając Agent Sandboxes.
- Agent mówi, że nie jest zalogowany, albo jego wywołania odpowiadają 401: token odłączono albo agent zalogował się do serwera App Platform. Zaloguj się ponownie z agenta (
/mcpw Claude Code). - Narzędzie odpowiada
WorkspaceChoice: token sięga kilku przestrzeni roboczych z sandboxami. Powiedz agentowi, której ma używać; wyśle jejworkspacew każdym wywołaniu. - Agent szuka
RunCommand: to nie jest narzędzie tego serwera. Wskaż muConnectSandboxi CLI albo zainstaluj plugin, którego skill to mówi. RESOURCE_EXHAUSTEDzLimitReached: vCPU przestrzeni roboczej zajmują jej działające i wstrzymane sandboxy. Poproś agenta, żeby usunął te, których już nie potrzebuje.
Pytania
Jaki jest adres serwera MCP?
https://mcp.pethost.dev/sandboxes, streamable HTTP, z logowaniem przez OAuth w przeglądarce.
Którzy agenci działają z Pethost Agent Sandboxes?
Każdy agent, który przyjmuje zdalny serwer MCP: Claude Code, Codex, Cursor, Claude w przeglądarce i na desktopie, Hermes Agent i inni. Claude Code i Codex mogą zainstalować plugin, który dodaje skill.
Czy agent może uruchamiać polecenia w sandboxie przez MCP?
Przez serwer samego sandboxa: ConnectSandbox podaje jego adres i token, a agent uruchamia polecenia przez CLI pethost albo curl. Sam serwer MCP tworzy, zmienia, wstrzymuje i usuwa sandboxy oraz robi ich forki.
Czy agent dostaje moje klucze API?
Nie. Dostaje token do przestrzeni roboczych, które wybierzesz. Klucze do modeli i usług to sekrety przestrzeni roboczej, których nie trzyma żaden sandbox ani żadna odpowiedź narzędzia.
Czy to ten sam serwer co w Pethost App Platform?
Nie: serwer App Platform to https://mcp.pethost.dev/mcp. Każdy ma własne narzędzia i tokeny.
Wypróbuj Pethost Agent Sandboxes
Okres próbny na 7 dni z 1 $ zużycia i 4 vCPU, z kartą. Potem plan od 20 $ miesięcznie, który zawiera tyle samo zużycia.