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

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

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

Обновлено 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, включая 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](https://pethost.dev/ru/docs/sandboxes/ssh/).

## Превью, которые спят

Запрос к порту песочницы на паузе будит ее: dev-сервер все еще работает с тем, что было у него в памяти, и первый ответ приходит примерно за 0,2 с. Поэтому превью ветки или работы агента может встать на паузу через несколько минут после последнего захода и стоить 30 % цены работы до следующего:

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

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

[ПредыдущаяКоманды и файлы в песочнице](https://pethost.dev/ru/docs/sandboxes/commands-and-files/) [СледующаяClaude Code, Codex и OpenCode в песочнице](https://pethost.dev/ru/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/ru/templates/)
- [О нас](https://pethost.dev/about/)
- [Документация](https://pethost.dev/docs/)
- [Блог](https://pethost.dev/ru/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/ru/postgres/)
- [Valkey](https://pethost.dev/ru/valkey/)

Agent Sandboxes

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

Сравнения

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

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

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