Polski
Menu dokumentacji

Dokumentacja Agent Sandboxes · Pierwsze kroki

Podłącz agenta do sandboxów przez MCP

Zaktualizowano · 5 min czytania

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.

W skrócie
  • 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 ConnectSandbox i CLI pethost albo curl.
  • 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.

Claude Code

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ędzieCo robi
GetWorkspaceLimity przestrzeni roboczej, rozmiary i ceny, nazwy jej sekretów i klucze SSH.
ListSandboxesJej sandboxy, od najnowszych, według stanu, etykiety albo nazwy.
CreateSandboxSandbox z szablonu, z odpowiedzią, gdy już działa.
GetSandboxJeden sandbox: jego stan i powód, ustawienia, jak się do niego dostać, zużycie.
UpdateSandboxJego nazwa, rozmiar, cykl życia, ruch wychodzący, publiczne porty albo środowisko.
PauseSandboxWstrzymuje go, z zachowaną pamięcią i procesami.
StopSandboxZatrzymuje go, z zachowanym dyskiem.
ResumeSandboxPonownie uruchamia wstrzymany albo zatrzymany.
ForkSandboxKopiuje go, łącznie z pamięcią i procesami, do nowych sandboxów.
DeleteSandboxUsuwa go, razem z pamięcią i dyskiem, na dobre.
ConnectSandboxSerwer sandboxa, token do niego i jego polecenie SSH.
CreateTemplateZapisuje dysk sandboxa jako szablon.
ListTemplatesNasze 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łanie SandboxRuntimeService po nazwie, w JSON-ie Connect, z nazwami pól takimi jak w narzędziach.
  • Bez powłoki agent podaje ci panel_url sandboxa, 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 (/mcp w Claude Code).
  • Narzędzie odpowiada WorkspaceChoice: token sięga kilku przestrzeni roboczych z sandboxami. Powiedz agentowi, której ma używać; wyśle jej workspace w każdym wywołaniu.
  • Agent szuka RunCommand: to nie jest narzędzie tego serwera. Wskaż mu ConnectSandbox i CLI albo zainstaluj plugin, którego skill to mówi.
  • RESOURCE_EXHAUSTED z LimitReached: 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.

Zacznij okres próbny