> ## Documentation Index
> Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Public and private ports

> Give a web server in a machine an HTTPS URL, for anyone or only for people with the link.

Publish a port and the CLI prints its URL, `https://<port>-<machine id without m_>.<domain>/`.

```bash theme={null}
instabox port publish dev 3000 --name 'Web app'           # anyone can open the URL
instabox port publish dev 3000 --private                  # prints a link with ?_token=; only it opens the URL
instabox port publish dev 3000 --private --rotate-token   # a new link; the old one stops working
instabox port publish dev 3000 --public                   # anyone again
instabox port ls dev
instabox port unpublish dev 3000
```

Inside the machine, an agent does the same with `instabox-port`. Where it is missing,
`instabox port setup dev` installs it.

```bash theme={null}
instabox-port publish 3000 --name 'Web app'
instabox-port publish 3000 --private
instabox-port serve ./report --port 8080      # serve a folder with an index.html
```

In the dashboard, a machine's **Ports** tab publishes and unpublishes ports and marks private ones. A
machine has up to 16 published ports.

> [!WARNING]
>
> The URL is not a secret. A **public** port (the default) lets anyone reach the whole service until you
> unpublish it.

## Share a private port

A private port answers only requests that carry its token. Everyone else gets `401`, and those requests
never wake the machine.

* **Browsers:** share the printed link, which is the URL with `?_token=ibp_…`. Opening it redirects to
  the plain URL and sets a cookie (`__Host-instabox_port_auth`). Every later request from that browser
  gets through, WebSockets included.
* **Scripts:** send `Authorization: Bearer ibp_…`.

> [!NOTE]
>
> You see the link once, because the server keeps only a hash. `--private --rotate-token` prints a new
> link and ends the old link's connections. Renaming a private port keeps it private, and `--public`
> drops the token.

## Visits wake a paused machine

A visit wakes a machine that paused itself after 30 idle minutes. The request waits for
the machine to resume, so a phone app or webhook can reach the URL without starting the machine first.
`instabox wake <machine>` does the same without a request.

A machine that **you** paused or stopped stays offline until you resume or start it, at the same URL.
After a stop, start your server again.

## Reach a port only from your computer

To reach a port without any URL, forward it over SSH: `instabox port-forward dev 8080:3000`. This works
for any TCP service, such as a database or a debugger. See
[SSH](https://instabox.sh/docs/access/ssh.md#forward-a-port-to-your-computer).

> [accordion] Response header size limit
>
> A response's header, meaning the status line and all fields, may be up to 24 KiB. A larger one, such
> as one with many or very large cookies, gets the platform's `502` page ("The sandbox service
> disconnected or is unavailable.") instead of the app's response.

> [accordion] Raw TCP ports (preview)
>
> Where the server enables it, `instabox port publish dev 5432 --tcp` prints
> `5432-<id>.<tcp domain>:443` for raw TCP, such as Postgres or Redis. Connect with TLS and that name
> as SNI:
>
> ```bash theme={null}
> psql "host=5432-<id>.<tcp domain> port=443 sslmode=require user=postgres"
> openssl s_client -connect <address> -servername <host>
> ```
>
> psql and libpq 14 and later send SNI. PG17 and later may add `sslnegotiation=direct`. For older
> clients, use stunnel or `instabox port-forward`.
>
> * The service in the machine sees plain TCP and must use its own password.
> * A raw TCP port is always public: `--private` does not apply to it.
> * It is in preview, for admins only, until the server opens it to everyone. Then it is for paid
>   plans only, with a per-workspace limit.
> * A connection counts as activity only while bytes flow. An idle pooled connection does not keep
>   the machine awake, so keep pool idle timeouts under 30 minutes or send keepalives.

> [card] [Preview URLs](https://instabox.sh/docs/use-cases/preview-urls.md)
>
> Share a running app from an agent's machine.

> [card] [Auto-pause and max-run](https://instabox.sh/docs/machines/auto-pause.md)
>
> When a machine pauses itself and what wakes it.