Документація Agent Sandboxes · Завдання
Секрети й вихідний трафік: ключі, яких пісочниця не тримає
Пісочниця виконує код, якому ви можете не довіряти: агента, користувача, пакета. Два налаштування тримають її в межах. Секрет — це ключ, якого пісочниця ніколи не тримає: вона бачить заглушку, а проксі вихідного трафіку підставляє справжній ключ у запит лише до названих вами хостів. Вихідний трафік — це список місць, куди вона взагалі може підключатися.
SetSecretзберігає значення в робочому просторі разом із його хостами; змінна, прив’язана до нього (EnvVar.secret), містить заглушку,phs_….- Підстановка: у заголовках HTTPS-запитів лише до хостів секрету, і в
Authorization, і вx-api-key. Нове значення працює одразу. egress.allowіdeny: домени, піддомени, IP і CIDR, порт, якщо це не 80 і 443;denyмає перевагу; типово — куди завгодно.- Виходять лише TCP і DNS, а DNS пісочниці відповідає лише на імена, які дозволяє список.
Step 1: Збережіть секрет із його хостами
Секрет має назву (a-z, 0-9 і «-»), значення й хости, на які значення можна надсилати. Задавайте його з власного середовища, ніколи з промпту чи файлу в пісочниці. Повторне задання замінює значення й хости разом.
import os
sandboxes.set_secret("openai", value=os.environ["OPENAI_API_KEY"], hosts=["api.openai.com"])
await sandboxes.setSecret({ name: "openai", value: process.env.OPENAI_API_KEY!, hosts: ["api.openai.com"] });
_, err = client.SetSecret(ctx, &sandboxes.SetSecretRequest{
Name: "openai",
Value: os.Getenv("OPENAI_API_KEY"),
Hosts: []string{"api.openai.com"},
})
sandboxes
.set_secret(SetSecretRequest {
name: "openai".into(),
value: std::env::var("OPENAI_API_KEY")?,
hosts: vec!["api.openai.com".into()],
..Default::default()
})
.await?;
$ printf %s "$OPENAI_API_KEY" | pethost sandbox secret set openai --host api.openai.com
✓ Set the secret openai for api.openai.com. Bind it: --env <VARIABLE>=secret:openai
openai
Step 2: Створіть пісочницю, що його прив’язує, зі списком дозволених адрес
Прив’яжіть змінну до секрету в environment пісочниці й перелічіть у egress.allow, куди вона може підключатися: тут — індекс пакетів Python і хост секрету. Вихідний трафік має дозволяти хости секрету.
from pethost.sandboxes import Egress, Environment, EnvVar, SandboxSettings
sandbox = sandboxes.create_sandbox("base", settings=SandboxSettings(
environment=Environment(variables=[EnvVar(name="OPENAI_API_KEY", secret="openai")]),
egress=Egress(allow=["pypi.org", "files.pythonhosted.org", "api.openai.com"]),
))
sandbox_id = sandbox.sandbox_id
const sandbox = await sandboxes.createSandbox({
template: "base",
settings: {
environment: { variables: [{ name: "OPENAI_API_KEY", secret: "openai" }] },
egress: { allow: ["pypi.org", "files.pythonhosted.org", "api.openai.com"] },
},
});
const sandboxId = sandbox.sandboxId;
sandbox, err := client.CreateSandbox(ctx, &sandboxes.CreateSandboxRequest{Template: "base", Settings: &sandboxes.SandboxSettings{
Environment: &sandboxes.Environment{Variables: []sandboxes.EnvVar{
{Name: "OPENAI_API_KEY", Source: sandboxes.EnvVarSecret("openai")},
}},
Egress: &sandboxes.Egress{Allow: []string{"pypi.org", "files.pythonhosted.org", "api.openai.com"}},
}})
if err != nil {
log.Fatal(err)
}
id := sandbox.SandboxID
let key = EnvVar { name: "OPENAI_API_KEY".into(), source: Some(EnvVarSource::Secret("openai".into())) };
let allow = ["pypi.org", "files.pythonhosted.org", "api.openai.com"].map(String::from).to_vec();
let sandbox = sandboxes
.create_sandbox(CreateSandboxRequest {
template: "base".into(),
settings: Some(SandboxSettings {
environment: Some(Environment { variables: vec![key] }),
egress: Some(Egress { allow, ..Default::default() }),
..Default::default()
}),
..Default::default()
})
.await?;
let id = sandbox.sandbox_id.clone();
$ pethost sandbox new --name fenced --env OPENAI_API_KEY=secret:openai \
--allow pypi.org --allow files.pythonhosted.org --allow api.openai.com
✓ Made sandbox fenced (xhww8xdrh7jj2d8c): default, running, from base@17, in <1 s
xhww8xdrh7jj2d8c
Next: pethost sandbox run xhww8xdrh7jj2d8c -- <command> · pethost sandbox shell xhww8xdrh7jj2d8c
CreateSandbox {"name": "fenced", "settings": {"environment": {"variables": [{"name": "OPENAI_API_KEY", "secret": "openai"}]}, "egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com"]}}}
Step 3: Подивіться, що бачить пісочниця
Усередині змінна містить заглушку, запит до хоста секрету несе ключ, а ім’я, якого список не дозволяє, навіть не резолвиться.
check = sandboxes.run_command(sandbox_id, command=(
'echo "$OPENAI_API_KEY" | cut -c1-8; '
'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; '
'curl -sS https://example.com'
))
print(check.stdout, check.stderr)
# phs_szjl
# 401
# curl: (6) Could not resolve host: example.com
const check = await sandboxes.runCommand({
sandboxId,
command:
'echo "$OPENAI_API_KEY" | cut -c1-8; ' +
'curl -s -o /dev/null -w "%{http_code}\\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ' +
"curl -sS https://example.com",
});
console.log(check.stdout, check.stderr);
check, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{SandboxID: id, Command: `echo "$OPENAI_API_KEY" | cut -c1-8; ` +
`curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; ` +
`curl -sS https://example.com`})
if err != nil {
log.Fatal(err)
}
fmt.Println(check.Stdout, check.Stderr)
let check = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: concat!(
r#"echo "$OPENAI_API_KEY" | cut -c1-8; "#,
r#"curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models; "#,
"curl -sS https://example.com",
)
.into(),
..Default::default()
})
.await?;
println!("{} {}", check.stdout, check.stderr);
Прогін вище зберіг вигаданий ключ, на який OpenAI відповів 401; ваш справжній ключ отримає 200. У будь-якому разі запит вийшов із пісочниці зі збереженим значенням замість заглушки.
Step 4: Змінюйте список на ходу
UpdateSandbox з групою egress одразу замінює весь список і закриває з’єднання, яких він більше не дозволяє. Новому значенню секрету нічого не треба: знову викличте SetSecret, і кожна пісочниця, що його прив’язує, надсилатиме нове значення з наступного запиту.
$ pethost sandbox set fenced --allow pypi.org --allow files.pythonhosted.org --allow api.openai.com --allow github.com:22
UpdateSandbox {"sandbox_id": "…", "settings": {"egress": {"allow": ["pypi.org", "files.pythonhosted.org", "api.openai.com", "github.com:22"]}}}
Як працює секрет
Значення секрету лежить у панелі, зашифроване, і в пам’яті серверів, де працюють пісочниці, що його прив’язують: ніколи на диску пісочниці, ніколи в її пам’яті, ніколи у відповіді API. Змінна, прив’язана до нього, містить заглушку, що починається з phs_, однакову для кожного процесу пісочниці.
Проксі вихідного трафіку пісочниці завершує TLS лише для хостів секрету, сертифікатом власного центру сертифікації сервера, якому пісочниця довіряє: Node, Python, curl і git налаштовано на нього. У кожному запиті до цих хостів він замінює заглушку значенням усюди, де вона трапляється в значенні заголовка: Authorization: Bearer, x-api-key, усередині облікових даних Authorization: Basic. Запит до будь-якого іншого хоста несе заглушку, яка там нічого не варта. Підстановка відбувається лише в заголовках, а не в тілі запиту.
- Хости записуються так само, як домени у вихідному трафіку:
api.openai.comабо*.example.comдля піддоменів, із портом, якщо це не 443. - Нове значення працює одразу, у кожній пісочниці, що працює, і в кожній копії, що прив’язує секрет.
- Прив’язаний секрет не можна видалити:
DeleteSecretвідхиляється, поки його прив’язує пісочниця, яку не видалено. - Робочий простір тримає 100 секретів.
GetWorkspaceперелічує їхні назви й хости, але ніколи значення.
Події вихідного трафіку кажуть для кожного хоста й хвилини, які секрети підставлено в його запити: спостережуваність.
Як працює вихідний трафік
egress пісочниці має два списки. allow каже, куди вона може підключатися, deny — куди не може, і deny має перевагу. Типово allow — це ["*"], куди завгодно. Надіслана група замінює всю групу: deny, надісланий сам, лишає allow порожнім, тож щоб заблокувати кілька хостів, надішліть разом із ними allow ["*"]. Разом вони вміщують 100 записів, кожен щонайбільше 255 байтів.
| Запис | Відкриває |
|---|---|
* | Куди завгодно. |
pypi.org | Цей домен, на портах 80 і 443. |
*.github.com | Його піддомени будь-якої глибини, але не сам github.com. |
github.com:22 | Цей домен на цьому порту: git по SSH. |
203.0.113.7, 203.0.113.0/24 | Ці адреси, коли з’єднання йде за адресою, з :port, якщо це не 80 і 443. |
- З пісочниці виходять лише TCP і DNS: ні UDP, тож ні QUIC чи HTTP/3, ні ping, хоч би що казав список.
- DNS відповідає лише на дозволені імена. Резолвер пісочниці відповідає REFUSED на ім’я, якого не дозволяє жоден доменний запис, нікого не питаючи, тож жодні дані не виходять у DNS-запитах.
- TLS перевіряється за ім’ям, яке надсилає клієнт, а проксі з’єднується з адресою, яку сам резолвив, і ніколи не з тією, яку обрала пісочниця. Доменний запис довіряє всьому, що віддається за адресами цього імені, зокрема іншим сайтам CDN: огорожа, яка має там витримати, називає IP або прив’язує до хоста секрет, і тоді проксі читає його запити один за одним.
- Звичайний HTTP перевіряється запит за запитом: на запит до іншого хоста, ніж хост з’єднання, приходить 421, а нове з’єднання клієнта перевіряється за цим хостом.
- SSH та інші протоколи не називають хоста й проходять лише до доменного запису з указаним портом, як-от
github.com:22. - Завжди відхиляються: приватні, link-local і CGNAT-адреси, сам сервер, порт 25 і HTTP/2 без TLS.
- Відмова, на яку проксі може відповісти, — це 403 із поясненням, що саме відмовило.
Кожна пісочниця має й власні межі: 200 нових з’єднань на секунду після сплеску в 1 000, 1 024 відкритих одночасно і 200 DNS-запитів на секунду.
Списки, що працюють
| Для чого | allow |
|---|---|
| pip і uv | pypi.org, files.pythonhosted.org |
| npm | registry.npmjs.org |
| git по HTTPS і SSH | github.com, *.githubusercontent.com, github.com:22 |
| Claude Code | api.anthropic.com |
| Codex | api.openai.com |
Стежте за подіями вихідного трафіку пісочниці протягом хвилини справжньої роботи, щоб дізнатися, що ще їй потрібно: кожна називає хост, чи його дозволено і скільки байтів пішло в кожен бік.
Коли не працює
- «Could not resolve host»: жоден запис не дозволяє це ім’я. Додайте його в
allow. - 403 із назвою політики вихідного трафіку: хост або його порт не дозволено, або спрацював запис
deny. SSH потребує порту в записі. - Сервіс відповідає 401 із прив’язаним секретом: запит пішов на хост, якого секрет не називає, або клієнт поклав ключ у тіло, де підстановки немає, або закріплює власні сертифікати. Назвіть хост у
hostsсекрету й надсилайте ключ у заголовку. INVALID_ARGUMENTпід час створення чи оновлення: вихідний трафік пісочниці не дозволяє хости прив’язаного секрету, або секрету не існує. Дозвольте їх або спершу задайте секрет.FAILED_PRECONDITIONнаDeleteSecret: його прив’язує пісочниця. Відв’яжіть його черезUpdateSandboxабо видаліть ту пісочницю.RESOURCE_EXHAUSTEDзLimitReached,secrets: у робочому просторі вже 100 секретів. Видаліть той, який більше не прив’язуєте.
Запитання
Чи може процес у пісочниці прочитати мій API-ключ?
Ні. Прив’язана змінна містить заглушку; проксі вихідного трафіку, поза ВМ, підставляє ключ у запити до хостів секрету.
Які запити отримують справжній ключ?
HTTPS-запити до хостів, які називає секрет, у їхніх заголовках. Кожен інший хост отримує заглушку.
Як заблокувати доступ до інтернету в пісочниці?
Надішліть egress з порожнім allow: нічого не вийде, а DNS нічого не резолвить. Додавайте лише те, що потрібно для роботи.
Чи є в пісочниці UDP?
Ні. З пісочниці виходять лише TCP і DNS, тож QUIC, HTTP/3 і ping не працюють, хоч би що казав список.
Чи діють зміни вихідного трафіку на пісочницю, що працює?
Так, одразу: з’єднання, яких новий список більше не дозволяє, закриваються.
Спробуйте Pethost Agent Sandboxes
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.