Документація Agent Sandboxes · Завдання
Порти й прев’ю: URL пісочниці
Кожен порт пісочниці має власну 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, зокрема WebSocket, із сертифікатом, який уже є; порт 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 пояснює, як увійти.
Прев’ю, що сплять
Запит до порту пісочниці на паузі будить її: сервер розробки досі працює з тим, що мав у пам’яті, а перша відповідь приходить приблизно за 0,2 с. Тож прев’ю гілки чи роботи агента може стати на паузу за кілька хвилин після останнього відвідування й коштувати 30% ціни роботи до наступного:
- Збережіть застосунок як шаблон зі встановленими залежностями, щоб нове прев’ю запускалося приблизно за 0,22 с (шаблони).
- Запускайте його з публічним портом і запущеним сервером розробки, стартованим із
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.»: сервер розробки 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.
Чи працюють WebSocket?
Так, на публічних портах, а на приватних — від клієнта, що надсилає заголовок, по HTTP/1.1 і HTTP/2.
Чи будить відвідування пісочницю на паузі?
Так: приблизно за 0,2 с, і її сервер досі працює. Зупинена прокидається так лише з wake_when_stopped.
Скільки портів можуть бути публічними?
До 20 на пісочницю. До будь-якого іншого порту можна дістатися з токеном.
Спробуйте Pethost Agent Sandboxes
Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.