Документация Agent Sandboxes · Задачи
Порты и превью: адреса песочницы
У каждого порта песочницы свой HTTPS-адрес, https://<port>-<sandbox id>.<server>. Сделайте порт публичным, и открыть его сможет кто угодно; оставьте приватным, и он будет отвечать только на запросы с его токеном. Запрос к порту песочницы на паузе будит ее, поэтому превью может спать между заходами.
wait_for_portуRunCommand: вызов отвечает, когда ваш сервер начал слушать, а сервер продолжает работать.- Публичные порты (
settings.ingress.public_ports, до 20) отвечают кому угодно, в том числе браузеру. - Приватные порты отвечают на запросы с
Pethost-Token: <token>изCreateLinkсport: для программ, curl иfetchсо страницы. - Заход будит песочницу на паузе примерно за 0,2 с, и ее сервер там же, где был.
Step 1: Запустите сервер и дождитесь его порта
Запустите сервер с wait_for_port. Вызов отвечает, как только на этом порту кто-то слушает, в пределах wait_seconds, а сервер продолжает работать. До сервера, который слушает localhost, тоже можно достучаться.
server = sandboxes.run_command(
sandbox_id,
command="python3 -m http.server 5173",
wait_for_port=5173,
)
print(server.state.name, server.command_id) # RUNNING zldikyia4nbt
const server = await sandboxes.runCommand({
sandboxId,
command: "python3 -m http.server 5173",
waitForPort: 5173,
});
console.log(server.state, server.commandId); // RUNNING
server, err := client.RunCommand(ctx, &sandboxes.RunCommandRequest{
SandboxID: id,
Command: "python3 -m http.server 5173",
WaitForPort: 5173,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(server.State, server.CommandID) // RUNNING
let server = sandboxes
.run_command(RunCommandRequest {
sandbox_id: id.clone(),
command: "python3 -m http.server 5173".into(),
wait_for_port: 5173,
..Default::default()
})
.await?;
println!("{:?} {}", server.state, server.command_id); // Running
$ pethost sandbox run api-dev -d --wait-for-port 5173 -- python3 -m http.server 5173
It runs on in the sandbox. Its output so far: pethost api GetCommand '{"sandbox_id": "e9bprbw1hovj6sw5", "command_id": "gqiwdee8y868"}'
gqiwdee8y868
Step 2: Сделайте порт публичным
Публичный порт задается в настройках ingress песочницы. UpdateSandbox заменяет всю группу, поэтому отправляйте все порты, которые должны остаться публичными; в ответе у каждого есть url.
from pethost.sandboxes import Ingress, PublicPort, SandboxSettings
sandbox = sandboxes.update_sandbox(
sandbox_id,
settings=SandboxSettings(ingress=Ingress(public_ports=[PublicPort(port=5173)])),
)
for port in sandbox.settings.ingress.public_ports:
print(port.port, port.url)
# 5173 https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
const updated = await sandboxes.updateSandbox({
sandboxId,
settings: { ingress: { publicPorts: [{ port: 5173 }] } },
});
for (const port of updated.settings?.ingress?.publicPorts ?? []) console.log(port.port, port.url);
updated, err := client.UpdateSandbox(ctx, &sandboxes.UpdateSandboxRequest{SandboxID: id, Settings: &sandboxes.SandboxSettings{
Ingress: &sandboxes.Ingress{PublicPorts: []sandboxes.PublicPort{{Port: 5173}}},
}})
if err != nil {
log.Fatal(err)
}
for _, port := range updated.Settings.Ingress.PublicPorts {
fmt.Println(port.Port, port.URL)
}
let ingress = Ingress { public_ports: vec![PublicPort { port: 5173, ..Default::default() }] };
let updated = sandboxes
.update_sandbox(UpdateSandboxRequest {
sandbox_id: id.clone(),
settings: Some(SandboxSettings { ingress: Some(ingress), ..Default::default() }),
..Default::default()
})
.await?;
for port in updated.settings.and_then(|settings| settings.ingress).map(|ingress| ingress.public_ports).unwrap_or_default() {
println!("{} {}", port.port, port.url);
}
$ pethost sandbox ports api-dev --open 5173
5173 https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
UpdateSandbox {"sandbox_id": "…", "settings": {"ingress": {"public_ports": [{"port": 5173}]}}}
Порт может быть публичным с самого начала: передайте тот же ingress в CreateSandbox или --public-port 5173 в pethost sandbox new.
Step 3: Или оставьте его приватным, за токеном
Любой непубличный порт отвечает только на запрос с заголовком Pethost-Token. CreateLink с port отвечает адресом порта и токеном только для этого порта, который истекает через час, если ttl_seconds не говорит иначе. Здесь второй сервер, запущенный как в первом шаге, слушает порт 8080.
link = sandboxes.create_link(sandbox_id, port=8080, ttl_seconds=3600)
print(link.url)
print(link.token)
# https://8080-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network/
# sbl.eyJzIjoiZTlicHJidzFob3ZqNnN3NSIs…
const link = await sandboxes.createLink({ sandboxId, port: 8080, ttlSeconds: 3600 });
const answer = await fetch(link.url, { headers: { "Pethost-Token": link.token } });
console.log(answer.status);
link, err := client.CreateLink(ctx, &sandboxes.CreateLinkRequest{
SandboxID: id,
Target: sandboxes.CreateLinkPort(8080),
TTLSeconds: 3600,
})
if err != nil {
log.Fatal(err)
}
fmt.Println(link.URL)
fmt.Println(link.Token)
let link = sandboxes
.create_link(CreateLinkRequest {
sandbox_id: id.clone(),
target: Some(CreateLinkRequestTarget::Port(8080)),
ttl_seconds: 3600,
})
.await?;
println!("{}", link.url);
println!("{}", link.token);
$ curl -H "$(pethost sandbox url api-dev 8080 --token | tail -1)" "$(pethost sandbox url api-dev 8080)"
Port 8080 is private: a request sends its token, which --token prints. A browser opens a public port: pethost sandbox ports e9bprbw1hovj6sw5 --open 8080
<!DOCTYPE HTML>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Directory listing for /</title>
…
Адрес порта
Адрес порта — https://<port>-<sandbox id>.<server>, где сервер — тот, на котором работает песочница, например https://5173-k7f3q2xy0a1b2c3d.sbx1.sandboxes.pethost.network. Берите его из ответа (PublicPort.url, Link.url), а не собирайте сами: остановленная песочница, которая запустится на другом сервере, сменит вместе с ним свои адреса.
Порт 443 говорит на HTTP/1.1 и HTTP/2, включая WebSockets, с уже готовым сертификатом; порт 80 отвечает редиректом на HTTPS и больше ничем. Порты песочницы обслуживают 896 запросов одновременно. Адреса всех песочниц лежат под одним доменом, поэтому сервер снимает Domain с cookie, которую устанавливает ответ: дайте cookie приложения префикс __Host-, который держит их на собственном адресе приложения.
Публичный или приватный
Публичный порт отвечает любому, у кого есть адрес: это нужно вкладке браузера, картинке или WebSocket, ведь они не могут отправить заголовок. Приватный порт проверяется прежде всего: на запрос без его токена или с токеном другого порта приходит 401 еще до того, как песочница проснется. Сервер снимает заголовок, а остальной запрос доходит до вашей программы таким, каким был отправлен, включая Authorization и Cookie. Он отвечает на CORS для любого источника, так что ваша страница может делать fetch к порту с токеном, который у нее есть. Токен подключения песочницы — это root внутри нее, и порт он не открывает: странице давайте токен порта.
Чтобы открыть приватный порт в своем браузере, пробросьте его по SSH: ssh -L 8080:localhost:8080 <sandbox id>@<server> -p 2222, затем откройте http://localhost:8080. Как войти, рассказывает страница SSH.
Превью, которые спят
Запрос к порту песочницы на паузе будит ее: dev-сервер все еще работает с тем, что было у него в памяти, и первый ответ приходит примерно за 0,2 с. Поэтому превью ветки или работы агента может встать на паузу через несколько минут после последнего захода и стоить 30 % цены работы до следующего:
- Сохраните приложение как шаблон с установленными зависимостями, чтобы новое превью запускалось примерно за 0,22 с (шаблоны).
- Запускайте его с публичным портом и работающим dev-сервером, запущенным с
wait_for_port. - Ставьте его на паузу пораньше, с
pause_after_idle_seconds120, и выключите таймер остановки (0), чтобы следующий заход всегда заставал его на паузе, а не остановленным. - Удалите его, когда ветку смержат, или поручите это
delete_after_idle_seconds.
Превью размера SMALL, на которое заходят 10 раз в день, так стоит около 4,26 $ в месяц: расчет — на странице «Оплата». Порт остановленной песочницы отвечает 503, «stopped: resume it», если в ее жизненном цикле не задан wake_when_stopped (жизненный цикл).
Если не работает
- 401 от порта: порт приватный, а в запросе не было токена, или он истек, или он от другого порта. Сделайте порт публичным или отправьте
Pethost-Tokenсо свежим токеном для этого порта. - Страница ошибки или нет ответа: в песочнице никто не слушает этот порт. Запускайте сервер с
wait_for_port, чтобы знать, что он слушает, и смотрите его вывод черезGetCommand. - 503 «stopped: resume it»: песочница остановлена.
ResumeSandboxзапускает ее, но процессов уже нет: запустите сервер снова или держите превью на паузе, а не остановленными. wait_for_portответил через 45 с без порта: сервер не успел начать слушать или слушает другой порт. Прочитайте его вывод.- 403 «Blocked request. This host is not allowed.»: dev-сервер Vite проверяет заголовок
Host, а адрес порта ему незнаком. Задайте емуserver: { allowedHosts: true }вvite.config.jsили добавьте хост адреса в этот список. - Вход не сохраняется: приложение установило cookie для более широкого домена, и сервер его снимает. Используйте cookie
__Host-.
Вопросы
Как получить публичный URL для порта в песочнице?
Добавьте порт в settings.ingress.public_ports через UpdateSandbox или выполните pethost sandbox ports <id> --open <port>. Его адрес — https://<port>-<sandbox id>.<server>.
Можно ли защитить порт паролем?
Приватный порт отвечает только на запросы с его токеном в заголовке Pethost-Token, который создает CreateLink. Для браузера пробросьте его через ssh -L.
Работают ли WebSockets?
Да, на публичных портах и на приватных — от клиента, который отправляет заголовок, по HTTP/1.1 и HTTP/2.
Будит ли заход песочницу на паузе?
Да: примерно за 0,2 с, и ее сервер все еще работает. Остановленная так просыпается, только если задан wake_when_stopped.
Сколько портов могут быть публичными?
До 20 на песочницу. До любого другого порта можно достучаться с токеном.
Попробуйте Pethost Agent Sandboxes
Пробный период на 7 дней: 1 $ использования и 4 vCPU, нужна карта. Затем тариф от 20 $ в месяц, в который входит столько же использования.