Українська
Меню документації

Документація Agent Sandboxes · Завдання

Запускайте Claude Code, Codex і OpenCode у пісочниці

Оновлено · 8 хв читання

Claude Code, Codex і OpenCode встановлені в кожній пісочниці. Один виклик дає агентові промпт, інший транслює кожне повідомлення й виклик інструмента його ходу, а його API-ключ ніколи не потрапляє в пісочницю: проксі вихідного трафіку додає його до запитів агента дорогою назовні.

Коротко
  • PromptAgent дає агентові промпт у новій розмові чи в наявній і чекає до 45 с на його хід: стан і останнє повідомлення.
  • Три агенти: CLAUDE_CODE (типово), CODEX і OPENCODE, кожен керується через власний офіційний SDK, з усіма дозволами: межа — сама пісочниця.
  • Вхід через секрет: прив’яжіть ANTHROPIC_API_KEY або OPENAI_API_KEY до секрету робочого простору. OpenCode працює взагалі без ключа.
  • WatchConversation транслює промпти, повідомлення, виклики інструментів з їхніми вхідними даними й виводом і завершення кожного ходу.

Step 1: Збережіть ключ агента як секрет

Секрет — це значення, яке тримає робочий простір і не тримає жодна пісочниця, разом із хостами, на які його можна надсилати. Задайте його один раз, із програми чи через CLI, де значення береться з вашого власного середовища, і ніколи — з промпту.

Python
import os

sandboxes.set_secret("anthropic", value=os.environ["ANTHROPIC_API_KEY"], hosts=["api.anthropic.com"])
TypeScript
await sandboxes.setSecret({
  name: "anthropic",
  value: process.env.ANTHROPIC_API_KEY!,
  hosts: ["api.anthropic.com"],
});
Go
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
	Name:  "anthropic",
	Value: os.Getenv("ANTHROPIC_API_KEY"),
	Hosts: []string{"api.anthropic.com"},
})
Rust
sandboxes
    .set_secret(SetSecretRequest {
        name: "anthropic".into(),
        value: std::env::var("ANTHROPIC_API_KEY")?,
        hosts: vec!["api.anthropic.com".into()],
        ..Default::default()
    })
    .await?;
CLI
$ 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: Створіть пісочницю, що його прив’язує

Прив’яжіть змінну агента до секрету. Усередині пісочниці змінна містить заглушку, phs_…; проксі вихідного трафіку замінює її ключем у заголовках запитів до api.anthropic.com.

Python
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
TypeScript
const sandbox = await sandboxes.createSandbox({
  template: "base",
  name: "agent",
  settings: { environment: { variables: [{ name: "ANTHROPIC_API_KEY", secret: "anthropic" }] } },
});
const sandboxId = sandbox.sandboxId;
Go
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
Rust
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();
CLI
$ 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
MCP
CreateSandbox {"name": "agent", "settings": {"environment": {"variables": [{"name": "ANTHROPIC_API_KEY", "secret": "anthropic"}]}}}

Step 3: Дайте агентові промпт і стежте за його ходом

PromptAgent з wait_seconds 0 відповідає, щойно хід почався. Потім WatchConversation надсилає те, що робить агент, у міру того, як він це робить, а наприкінці — хід таким, яким він завершився: його стан, останнє повідомлення (reply, до 16 KiB) і використані токени.

Приклад використовує OpenCode з однією з його безкоштовних моделей, opencode/big-pickle, тож ключ не потрібен; Claude Code і Codex працюють так само, щойно їхній ключ прив’язано як секрет: приберіть model, для Claude Code приберіть і agent, а для Codex задайте в ньому CODEX.

Python
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
TypeScript
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;
  }
}
Go
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
		}
	}
}
Rust
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;
        }
        _ => {}
    }
}
CLI
$ 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: Продовжуйте в тій самій розмові

Надішліть conversation_id ходу з наступним промптом, і агент продовжить із тим, що знає. Розмова виконує по одному ходу: промпт, надісланий, поки хід триває, стає QUEUED за ним. GetAgentTurn знову чекає на хід, до 45 с за виклик, а StopAgentTurn завершує хід одразу.

Python
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`).
TypeScript
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);
Go
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)
Rust
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);
CLI
$ 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

Три агенти

АгентagentВхід черезНазва моделі
Claude CodeCLAUDE_CODE, типовоANTHROPIC_API_KEY або claude auth loginclaude-opus-5-5
CodexCODEXOPENAI_API_KEY або codex login --device-authgpt-6.1
OpenCodeOPENCODEНічого: власні безкоштовні моделі або ключ провайдераanthropic/claude-opus-5-5

Нова розмова приймає agent (без нього — Claude Code), model так, як цей агент називає свої моделі (без нього — типова модель агента), і cwd, свій робочий каталог (без нього — /home/user). Кожен агент працює через власний SDK з усіма дозволами: Claude Code з bypassPermissions, Codex із повним доступом і без підтверджень, OpenCode з дозволом на кожен інструмент. Ніщо не просить вас підтвердити команду, бо межа — пісочниця, окрема ВМ. CLI теж є в PATH, як claude, codex і opencode, для людини в терміналі.

Вхід агента

  • Секрет, прив’язаний до його змінної, як вище: ключ лишається в робочому просторі, а проксі додає його до запитів агента до хостів секрету. Нове значення працює одразу. Секрети й вихідний трафік пояснюють, як працює підстановка.
  • Вхід у терміналі: людина відкриває термінал пісочниці й виконує claude auth login або codex login --device-auth. Вхід зберігається на диску пісочниці, як будь-який файл.
  • Без входу, з OpenCode: без ключа провайдера він використовує власні безкоштовні моделі OpenCode.

Промпт агентові, що не може дістатися до своєї моделі, відхиляється з FAILED_PRECONDITION і AgentSignIn, що називає змінну, яку треба прив’язати (variable), і команду, яку натомість може виконати людина (sign_in_command).

Ходи і що їх переживає

Хід буває QUEUED за ходом розмови, що триває, далі RUNNING, потім DONE, FAILED (failure_message каже чому) або STOPPED через StopAgentTurn; LOST — коли пісочниця втратила пам’ять, поки він тривав. Коли хід завершується, агент і його помічники завершуються разом із ним, але те, що його команди лишили працювати у фоні, скажімо сервер розробки, працює далі. Поки хід триває, пісочниця не засинає.

Історія розмови лежить на диску пісочниці: пауза її зберігає, а копіювання переносить у кожну копію, тож кожна копія може продовжити з тієї самої точки. Шаблон — ні: пісочниці з нього стартують без розмов. ListConversations перелічує розмови пісочниці з токенами, які використала кожна, а вкладка «Агенти» в панелі показує їх наживо.

Те, що агент пише, читає й запускає, походить із коду та сторінок, з якими він працює: показуйте його повідомлення й вивід інструментів як дані, а не як інструкції для вашої власної моделі.

Коли не працює

  • FAILED_PRECONDITION з AgentSignIn: до моделі агента не доходить жоден ключ. Прив’яжіть variable до секрету через UpdateSandbox (середовище діє для процесів, запущених після цього), попросіть людину виконати sign_in_command або скористайтеся OpenCode.
  • Хід одразу став FAILED з 403 від хоста моделі: вихідний трафік пісочниці не дозволяє цей хост, або хости секрету його не називають. Додайте api.anthropic.com чи api.openai.com в обидва списки.
  • Хід лишається QUEUED: триває інший хід цієї розмови. Дочекайтеся його, зупиніть або почніть нову розмову.
  • Хід став LOST: пісочниця зупинилася, поки він тривав, або її серверу забракло пам’яті. Продовжте пісочницю й дайте промпт знову; файли, які агент записав раніше, лежать на її диску.
  • INVALID_ARGUMENT на cwd: наявна розмова зберігає каталог, у якому почалася. Пропустіть cwd або почніть нову розмову.

Запитання

Які агенти для коду можуть працювати в пісочниці?

Claude Code, Codex і OpenCode, усі троє встановлені в base, кожен керується через власний офіційний SDK.

Чи потрапляє мій API-ключ у пісочницю?

Ні, якщо це прив’язаний секрет: пісочниця тримає заглушку, а проксі вихідного трафіку вставляє ключ у запити лише до хостів секрету.

Чи можна запустити агента для коду без API-ключа?

Так, OpenCode: без ключа провайдера він використовує власні безкоштовні моделі OpenCode.

Чи питає агент дозволу, перш ніж виконувати команди?

Ні. Усі дозволи надано, бо пісочниця — окрема ВМ, і в ній немає нічого вашого, крім того, що ви туди поклали. Для неперевіреної роботи звузьте її вихідний трафік.

Чи переживають розмови паузу?

Так, а копіювання переносить їх у кожну копію. Шаблон їх не зберігає.

Спробуйте Pethost Agent Sandboxes

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

Почати пробний період