/boxd-preview on a pull request and get a clickable *.boxd.sh URL back in seconds. Reviewers click it and land on a full Linux VM running the branch’s exact code. Close the PR and the fork is destroyed automatically.
Each preview is a real VM forked from your golden, not a shared staging environment. Two reviewers can poke at two different PRs without stepping on each other’s writes. The whole thing is wired up by one Claude Code slash command — /boxd-setup-preview.
How it works
You keep one long-running golden VM with the app fully installed and running. It auto-suspends when nobody’s hitting it, so idle cost stays near zero. When someone comments/boxd-preview, a listener on the golden forks it (~160ms), gets the fork serving the right code, and posts the fork’s URL back as a comment. Forks land on the same worker as the source, so there’s no network setup and no warm-up time.
What “the right code” means depends on where you comment:
| Comment | What the preview serves |
|---|---|
/boxd-preview on a PR | the PR’s branch |
/boxd-preview on an issue | the golden as-is — no git work, the fastest path |
/boxd-preview branch=<ref> | any branch you name (works on issues and PRs) |
/boxd-preview --fix | the same, plus Claude makes a change — see fix-on-issue |
/boxd-preview any time to refresh the same fork. Closing the PR destroys it.
Setup
Set up a golden first. Previews fork an existing golden, so run
/boxd-setup-golden before this one.- From your laptop
- Inside the golden (in-VM)
Install the boxd CLI (this also drops the skills), then run the skill in the repo:
Claude Code only for now — reach out if you want it packaged for Codex, OpenCode, or any other agent.
- Detects your stack (docker-compose / npm / cargo / Procfile, …) and confirms the up / reload / rebuild commands with you — these are written to one config file on the golden,
/etc/boxd-platform.conf. Nothing is committed to your repo. - Probes fork-portability and reports anything that breaks when the app is served from a fresh hostname (e.g. a dev server’s host allowlist, hardcoded origins). You apply those fixes in your repo.
- Installs a
webhook(8)listener on the golden athooks.<golden>.boxd.shand registers two GitHub webhooks: the/boxd-previewcomment trigger and a PR-close teardown. The HMAC secret stays on the golden and in GitHub’s webhook config — never in your repo.
/var/log/golden-preview/<vm>.log), so a stuck preview is always debuggable.
Patterns
Refresh on new commits
Re-comment/boxd-preview after pushing. The same fork (named for the PR/issue) is re-synced in place — git fetch + reset, then hot-reload or rebuild as the diff demands. No fork churn; reviewers refresh the same URL.
Stable URL per PR
The fork is named for the PR/issue number, so a PR gets a predictablehttps://<repo>-pr-<n>.boxd.sh that survives across refreshes. Handy for screenshot diffs and Playwright runs targeting the preview.
Preview the golden as-is
/boxd-preview on an issue with no branch skips all git work and just serves the golden’s current state — a fast way to hand someone a throwaway copy of the running app.
Multi-service apps
If your app is more than one service (api + web + worker), put the orchestration inside the golden’spm2 / systemd / docker compose setup. The fork inherits it, and the up command you set during setup brings everything back against the new code.
Prefer automatic on every PR open?
The skill is on-demand (you comment to trigger), which keeps forks to PRs people are actually reviewing. If you’d rather fork automatically on everypull_request open/synchronize, wire a GitHub Actions workflow that calls boxd fork + boxd exec instead — the boxd CLI reads BOXD_API_KEY from the environment. Reach out if you want this as a turnkey variant.
FAQ
What happens if 5 PRs get previews at once?
What happens if 5 PRs get previews at once?
You get 5 forks, one per PR. The default cap is 10 VMs per user. Email
contact@boxd.sh if you need more.Does the fork have access to my real database?
Does the fork have access to my real database?
Only if your golden does. By default the golden runs a local DB and the fork inherits a snapshot. Perfect for preview data. Wire it to a real DB the same way you would in any CI workflow.
Does the fork cost money while nobody's clicking it?
Does the fork cost money while nobody's clicking it?
Forks auto-suspend on network idle and resume sub-ms on the next request. A PR sitting open over the weekend costs effectively nothing. Issue-mode previews that have no PR-close event are also reclaimed by a periodic TTL sweep.
Why didn't my dependency change show up?
Why didn't my dependency change show up?
The platform rebuilds only when the diff touches the paths you marked as rebuild triggers (lockfiles, schema, …) during setup. If a change isn’t reflecting, check
/var/log/golden-preview/<vm>.log on the golden — the deploy step logs which action it picked and why.Next
Deploy on push
Ship to your golden on every push to main.
Fix on issue
/boxd-fix or /boxd-preview --fix — Claude makes the change, you get a PR with a preview URL.