---
title: "Порти й прев’ю: URL пісочниці | Pethost Agent Sandboxes"
description: "Дайте будь-якому порту пісочниці HTTPS-адресу, публічну чи за токеном, дочекайтеся сервера розробки й запускайте прев’ю, що сплять між відвідуваннями."
---

[Документація Agent Sandboxes](https://pethost.dev/uk/docs/sandboxes/) · Завдання

# Порти й прев’ю: URL пісочниці

Оновлено 22 листопада 2026 р. · 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, зокрема 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](https://pethost.dev/uk/docs/sandboxes/ssh/) пояснює, як увійти.

## Прев’ю, що сплять

Запит до порту пісочниці на паузі будить її: сервер розробки досі працює з тим, що мав у пам’яті, а перша відповідь приходить приблизно за 0,2 с. Тож прев’ю гілки чи роботи агента може стати на паузу за кілька хвилин після останнього відвідування й коштувати 30% ціни роботи до наступного:

- **Збережіть застосунок як шаблон** зі встановленими залежностями, щоб нове прев’ю запускалося приблизно за 0,22 с ([шаблони](https://pethost.dev/uk/docs/sandboxes/templates/)).
- **Запускайте його з публічним портом** і запущеним сервером розробки, стартованим із `wait_for_port`.
- **Ставте його на паузу рано**, з `pause_after_idle_seconds` `120`, і вимкніть таймер зупинки (`0`), щоб наступне відвідування завжди заставало його на паузі, а не зупиненим.
- **Видаліть його**, коли гілку злито, або доручіть це `delete_after_idle_seconds`.

Прев’ю розміру SMALL, яке відвідують 10 разів на день, так коштує приблизно 4,26 $ на місяць: розрахунок — в [оплаті](https://pethost.dev/uk/docs/sandboxes/billing/#examples). Порт зупиненої пісочниці відповідає 503, «stopped: resume it», якщо її життєвий цикл не каже `wake_when_stopped` ([життєвий цикл](https://pethost.dev/uk/docs/sandboxes/lifecycle/#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 на пісочницю. До будь-якого іншого порту можна дістатися з токеном.

[НазадВиконуйте команди й редагуйте файли в пісочниці](https://pethost.dev/uk/docs/sandboxes/commands-and-files/) [ДаліЗапускайте Claude Code, Codex і OpenCode у пісочниці](https://pethost.dev/uk/docs/sandboxes/coding-agents/)

## Спробуйте Pethost Agent Sandboxes

Пробний період на 7 днів із використанням на 1 $ і 4 vCPU, потрібна картка. Далі — тариф від 20 $ на місяць, який включає стільки ж використання.

[Почати пробний період](https://console.pethost.dev/)

Pethost · Stephan Gomer · NIP 1133096755

Pethost

- [Шаблони](https://pethost.dev/uk/templates/)
- [Про нас](https://pethost.dev/about/)
- [Документація](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/uk/blog/)
- [API](https://pethost.dev/docs/api/)
- [CLI](https://pethost.dev/docs/cli/)
- [Плагін](https://github.com/pethost-dev/plugin)
- [Умови](https://pethost.dev/terms/)
- [Конфіденційність](https://pethost.dev/privacy/)
- [Повернення коштів](https://pethost.dev/refunds/)
- [support@pethost.dev](mailto:support@pethost.dev)

Бази даних

- [Postgres](https://pethost.dev/uk/postgres/)
- [Valkey](https://pethost.dev/uk/valkey/)

Agent Sandboxes

- [Пісочниці](https://pethost.dev/uk/sandboxes/)
- [Тарифи](https://pethost.dev/uk/sandboxes/#pricing)
- [Документація](https://pethost.dev/uk/docs/sandboxes/)
- [API](https://pethost.dev/docs/sandboxes/api/)

Порівняння

- [Coolify vs Dokploy vs CapRover vs Dokku](https://pethost.dev/uk/blog/coolify-vs-dokploy-vs-caprover-vs-dokku/)
- [Coolify Cloud vs Dokploy Cloud](https://pethost.dev/uk/blog/coolify-cloud-vs-dokploy-cloud/)
- [Ціни Railway vs Render vs Fly.io](https://pethost.dev/uk/blog/railway-vs-render-vs-fly-io-pricing/)
- [Керований хостинг Docker Compose](https://pethost.dev/uk/blog/managed-docker-compose-hosting/)

Альтернативи

- [Альтернативи Railway](https://pethost.dev/uk/blog/railway-alternatives/)
- [Альтернативи Heroku](https://pethost.dev/uk/blog/heroku-alternatives/)
- [Альтернативи Dokploy](https://pethost.dev/uk/blog/dokploy-alternatives/)
- [Альтернативи Coolify](https://pethost.dev/uk/blog/coolify-alternatives/)
- [Альтернативи Render](https://pethost.dev/uk/blog/render-alternatives/)
- [Альтернативи Sliplane](https://pethost.dev/uk/blog/sliplane-alternatives/)
