# Previews

A preview gives a port in a running sandbox its own HTTPS URL: `https://<slug>-<port>.groundbox.page`. It carries HTTP/1.1, streamed responses and WebSockets, so a dev server's hot reload works. Previews are on every plan.

## Make one

```
curl https://api.groundbox.dev/v1/sandboxes/sbx_.../previews \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"port": 3000}'
```

The answer has the preview's `url`. Asking again for the same port returns the same URL.

The CLI, with `--public` for a public one:

```
groundbox sandbox preview sbx_... 3000
groundbox sandbox preview sbx_... 3000 --public
```

The SDKs have `expose_port`, in TypeScript and Python:

```
import { Groundbox } from "@groundbox/sdk";

const groundbox = new Groundbox();
const preview = await groundbox.expose_port("sbx_...", 3000);
console.log(preview.url, preview.share_url);
```

For agents, the MCP tool `expose_port`. In the dashboard, the Previews tab of the sandbox's page.

List a sandbox's previews, make one public or private, or delete one:

```
curl https://api.groundbox.dev/v1/sandboxes/sbx_.../previews \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY"

curl -X PATCH https://api.groundbox.dev/v1/sandboxes/sbx_.../previews/3000 \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public": true}'

curl -X DELETE https://api.groundbox.dev/v1/sandboxes/sbx_.../previews/3000 \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY"
```

## Private by default

Members of the team who are signed in to the dashboard can open `url`. Anyone else needs `share_url`, which has a token and works for 24 hours (until `expires_at`). In a browser, the token becomes a cookie on that preview's host and is removed from the address bar. A script can send the token in the `X-Groundbox-Preview-Token` header instead of the `gb_token` query parameter:

```
curl https://<slug>-3000.groundbox.page/api/health \
  -H "X-Groundbox-Preview-Token: <the gb_token value from share_url>"
```

A private preview takes fetches and WebSockets that pages make only from its own sandbox's previews: a front end on one port can call an API on another. A page on any other site gets 403.

## Public

With `"public": true`, anyone with the URL can open it: for webhooks, OAuth callbacks and sharing. A browser that is not signed in to the team sees a short notice once ("Visit site") before the app. Webhooks and other clients that are not browsers never see it.

## Your app

- Listen on `0.0.0.0`, not `127.0.0.1` or `localhost`. Vite: `vite --host`. Next.js: `next dev -H 0.0.0.0`.
- The app gets `Host: localhost:<port>`, so the host checks of dev servers (Vite, Django, Rails) pass. The public host is in `X-Forwarded-Host`, and `X-Forwarded-Proto` is `https`.
- Build OAuth redirect URLs from `X-Forwarded-Host` or from config.

## What we change

- Cookies named `gb_*` and the token are not passed to the app.
- A `Domain` attribute on the app's `Set-Cookie` is dropped, so cookies stay on the preview's own host.
- Paths under `/__groundbox/` are ours: the notice and the report page.
- Responses get `X-Robots-Tag: noindex`.

## Your own domain

Serve a preview on a domain or subdomain you own, like `preview.example.com`. Three steps: add the domain, prove it is yours with two DNS records, and attach it to a sandbox port that has a preview.

```
groundbox domains add preview.example.com
# add the two DNS records it prints, then:
groundbox domains verify preview.example.com
groundbox domains attach preview.example.com sbx_... 3000
```

The API is `POST /v1/domains`, `POST /v1/domains/{domain}/verify` and `PATCH /v1/domains/{domain}`. The SDKs have `create_domain`, `verify_domain` and `attach_domain`.

```
curl https://api.groundbox.dev/v1/domains \
  -H "Authorization: Bearer $GROUNDBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "preview.example.com"}'
```

The answer lists the two records.

- A `TXT` record at `_groundbox-challenge.` your domain. It proves you control the domain. Leave it in place.
- A `CNAME` from your domain to the name we give you. If your DNS host proxies traffic, switch the proxy off for this record.

When both are found the domain is verified and we issue its certificate. `status` goes from `pending_dns` to `issuing` to `active`. Issuing takes from a few minutes to an hour. Until it is `active`, the domain does not answer over HTTPS.

- The domain serves exactly what the preview serves, with the same public or private setting.
- A public preview on your own domain opens straight away, with no notice page first.
- The domain is your team's, not the sandbox's. When the sandbox ends the domain is kept, verified, and you attach it to the next one. A change takes a few seconds to show.
- One name per domain entry. Wildcards are not supported.
- If your domain has CAA records, they must allow the certificate authority. A refused certificate shows as `failed`, with the reason.

## TCP ports

A preview is HTTP. For anything else in a sandbox, such as a database, SSH or a debugger, open a tunnel. The CLI listens on your machine and carries each connection to the port in the sandbox.

```
groundbox sandbox tcp sbx_... 5432
# in another terminal:
psql -h 127.0.0.1 -p 5432 -U postgres
```

`--listen` picks another local port or address. The tunnel uses your API key, so the port is never open to the internet, and nothing needs to change in the sandbox. It runs until you stop it.

From code, the TypeScript SDK has `connect_tcp(id, port)`. Underneath it is a WebSocket at `/v1/sandboxes/{id}/tcp/{port}` whose binary messages are the connection's bytes.

- There is no public address for a TCP port. A client connects through the tunnel.
- A connection lasts up to 60 minutes, then the client reconnects.
- The service in the sandbox must listen on `0.0.0.0`, not only `127.0.0.1`.

## Limits

- 10 previews per sandbox.
- Request bodies up to 32 MB.
- A WebSocket lasts up to 60 minutes, then the client reconnects.
- About 100 open connections and 1,200 requests a minute per sandbox.
- 20 GB of traffic per sandbox, then `429`.

## Lifetime

A preview ends when its sandbox ends. A paused sandbox's previews answer `503` until it resumes, at the same URL. So do a stopped sandbox's, until it starts. Traffic does not renew the timeout: the sandbox still stops at its timeout.

## Previews wake a sleeping sandbox

With [an idle pause](https://groundbox.dev/docs/sandboxes#idle), a request to a preview wakes the sandbox. The request is held while it resumes and is then served, so a link, a webhook or an OAuth callback works while the sandbox sleeps. Preview traffic counts as activity and keeps it awake. Start the server so that its command returns (`nohup ... &`): a command that is still running keeps the sandbox awake.

- Only a request that may see the preview wakes it. On a private preview that is a team member or a share link.
- On a public preview, a visitor's browser sees the notice first. The sandbox wakes when they go on. Webhooks and scripts wake it directly.
- Visitors of a public preview can wake a sandbox a limited number of times an hour. Past that the preview answers `429` with `Retry-After` and the sandbox stays asleep. Your team and share links are not limited.
- When the sandbox is not up in time, a browser gets a page that reloads by itself and other clients get `503` with `Retry-After`.
- A sandbox you paused yourself, or one with `wake_on_request: false`, answers `503` as before.

## Abuse

No phishing, no malware, and no login pages that pretend to be another company. Report a preview at `https://<host>/__groundbox/report`, or with `POST /v1/previews/report` (no key; `reason` is one of `phishing`, `malware`, `spam`, `illegal`, `other`). We can turn a preview off.
