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 --publicThe 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, not127.0.0.1orlocalhost. 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 inX-Forwarded-Host, andX-Forwarded-Protoishttps. - Build OAuth redirect URLs from
X-Forwarded-Hostor from config.
What we change
- Cookies named
gb_*and the token are not passed to the app. - A
Domainattribute on the app'sSet-Cookieis 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_... 3000The 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
TXTrecord at_groundbox-challenge.your domain. It proves you control the domain. Leave it in place. - A
CNAMEfrom 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 only127.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, 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
429withRetry-Afterand 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
503withRetry-After. - A sandbox you paused yourself, or one with
wake_on_request: false, answers503as 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.