Документация 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 $ в месяц, в который входит столько же использования.