Русский
Меню документации

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

Порты и превью: адреса песочницы

Обновлено · 6 мин чтения

У каждого порта песочницы свой 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, тоже можно достучаться.

Python
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
TypeScript
const server = await sandboxes.runCommand({
  sandboxId,
  command: "python3 -m http.server 5173",
  waitForPort: 5173,
});
console.log(server.state, server.commandId); // RUNNING
Go
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
Rust
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
CLI
$ 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.

Python
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
TypeScript
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);
Go
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)
}
Rust
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);
}
CLI
$ pethost sandbox ports api-dev --open 5173
5173   https://5173-e9bprbw1hovj6sw5.sbx1.sandboxes.pethost.network
MCP
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.

Python
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…
TypeScript
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);
Go
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)
Rust
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);
CLI
$ 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_seconds 120, и выключите таймер остановки (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 $ в месяц, в который входит столько же использования.

Начать пробный период