> ## 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.

# Preview URLs

> Run a dev server in a machine and share an HTTPS link to it.

At the end of this page, your app runs in a machine and anyone you send the link to can open it: a
reviewer, a phone, or a webhook sender. A published port gets an HTTPS URL. A private port opens only
with the link that carries its token.

**1. Start the dev server**

The commands below use `my-app` and `npm run dev` as stand-ins for your own app's folder and
start command.

```bash theme={null}
instabox create --name dev
cd my-app && instabox push dev .                                   # into /data/home/my-app
instabox exec --background dev --cwd /data/home/my-app -- npm run dev   # serves on port 3000
```

`push` reports how many files it pushed to `dev:/data/home/my-app`. `exec --background` prints
the job's ID and the `instabox jobs logs` command that follows it.

`--background` keeps the server running after the command returns. With a plain `exec`, start
the server with `nohup ./server >server.log 2>&1 &`, and redirect both stdout and stderr.

**2. Publish the port**

```bash theme={null}
instabox port publish dev 3000 --name 'Web app'   # public: anyone with the URL
instabox port publish dev 3000 --private          # only the printed ?_token= link opens it
```

The command prints the URL, `https://<port>-<machine id without m_>.<domain>/`. For a private
port it prints the link with `?_token=` instead.

> [!WARNING]
>
> A public URL is not a secret. Anyone can reach the whole service until you unpublish it.

**3. Share the link**

Send the printed URL. A browser that opens a private link gets a cookie and goes on to the plain
URL, WebSockets included. Scripts send `Authorization: Bearer ibp_...` instead. Everyone else
gets `401`.

**4. Rotate or remove the link**

```bash theme={null}
instabox port ls dev
instabox port publish dev 3000 --private --rotate-token   # a new link; the old one stops working
instabox port unpublish dev 3000
```

`port ls` shows each published port with its access and URL.

> [!NOTE]
>
> A visit wakes a machine that paused itself for being idle. The request waits for the machine to
> resume. A machine **you** paused or stopped stays offline at the same URL until you resume or start
> it. After a stop, start your server again.

An agent inside the machine publishes ports with `instabox-port`. Where `instabox-port` is missing,
`instabox port setup dev` installs it.

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

> [accordion] Only for you: port-forward
>
> `instabox port-forward dev 8080:3000` makes port 3000 reachable at `http://127.0.0.1:8080` on your
> computer until Ctrl-C, with no URL at all. It reaches any TCP service.

> [accordion] Limits
>
> A machine has up to 16 published ports. A response header may be up to 24 KiB. A larger one gets
> the platform's `502` page. Requests to a private port without its token never wake the machine.

> [card] [Public and private ports](https://instabox.sh/docs/access/ports.md)
>
> Public, private, and raw TCP ports in full.

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