Fork from a golden

Build your app once on a long-running “golden” VM (deps installed, migrations run, services started), then boxd fork yourapp-golden whenever you need an instant-ready copy. Each fork inherits the full disk state and boots in ~160ms.

Throughout this page we call the golden yourapp-golden to match the boxd-setup-golden skill’s default of <repo-name>-golden. Pick whatever name fits your project.

How it works

A golden VM is just a regular box that you’ve set up the way a fresh laptop would look after onboarding: repo cloned, dependencies installed, services running. You leave it on. Auto-suspend keeps idle cost near zero. When you fork, boxd snapshots the source disk, attaches a copy to a new VM on the same worker, and brings it up. Code, packages, running daemons, database files, all preserved. The fork gets its own name, IP, HTTPS domain, and 100 GB disk. No rebuild, no reinstall, no waiting for npm install or container layers.

Set up the golden

The fastest path is the Claude Code skill — it reads your repo (README, manifests, AGENTS.md) and installs + starts your app for you. Run it from your laptop (provisions a fresh VM over the API) or inside the VM (boxd new, open an agent shell, and the box you’re on becomes the golden):

/boxd-setup-golden

Claude Code only for now — reach out for Codex, OpenCode, or any other agent.

Full walkthrough of both paths: Set up a golden. If you’d rather do it by hand:

boxd new --name=yourapp-golden
ssh yourapp-golden.boxd.sh
# inside the VM
git clone https://github.com/you/yourapp.git
cd yourapp && ./scripts/setup.sh
# start your services as you normally would, e.g. via systemd or pm2
exit

Leave it running. Auto-suspend takes over when nothing is hitting it.

Fork it

SSH
CLI
TypeScript
Python

ssh boxd.sh fork yourapp-golden --name=pr-482

No install required. --json works here too.

boxd fork yourapp-golden --name=pr-482

    name: pr-482
      id: 7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678
     url: pr-482.boxd.sh
  forked: yourapp-golden
    boot: 160ms

Connect via SSH: ssh pr-482.boxd.sh
Or from your browser: https://pr-482.boxd.sh

Add --json for a parseable response:

boxd fork yourapp-golden --name=pr-482 --json

{
  "name": "pr-482",
  "vm_id": "7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678",
  "url": "pr-482.boxd.sh",
  "image": "default",
  "status": "running",
  "boot_time_ms": 160,
  "forked_from": "yourapp-golden"
}

import { Compute } from "@boxd-sh/sdk";

const c = new Compute();                                            // reads BOXD_API_KEY
const fork = await c.box.fork("yourapp-golden", { name: "pr-482" });
console.log(fork.url, fork.bootTimeMs, fork.forkedFrom);

from boxd import Compute

c = Compute()                                              # reads BOXD_API_KEY
fork = c.box.fork("yourapp-golden", name="pr-482")
print(fork.url, fork.boot_time_ms)

If you omit --name, the fork is named {source}-fork. Pick your own name when that collides.

Patterns

Per-PR previews

Fork the golden on every pull request, apply the branch diff inside the fork, post the pr-482.boxd.sh URL as a comment. Destroy on merge. See Per-PR preview URLs.

Per-issue agent runs

Label an issue (or PR) boxd-fix. A GitHub webhook fires a listener on the golden, which forks the VM, hands the fork to Claude Code via boxd exec, the agent edits inside the fork, and the handler opens a PR (or pushes commits to the existing PR) with the preview URL attached. See Fix on issue.

Bug repro

Fork production state into an isolated copy, reproduce the bug there, throw the fork away when you’re done. The source VM is untouched.

boxd fork prod --name=repro-bug-91
ssh repro-bug-91.boxd.sh
# poke at it freely
boxd destroy repro-bug-91

FAQ

How fresh is the data in a fork?

The fork takes a point-in-time snapshot of the source disk at the moment of the fork. Anything written to the source after that point won’t be in the fork.

Do running services come up automatically in the fork?

Yes. systemd starts the same units the source had enabled. Long-lived processes that were running at fork time come back up the way they were configured to.

How many forks can I run at once?

Up to 10 VMs per account total, extendable on request. Forks count toward this limit.

Does the golden need to stay running?

It can be suspended. Forks work against a suspended source too. Auto-suspend keeps idle cost low without breaking the workflow.

Per-PR preview URLs

Wire forks into GitHub webhooks and ship a URL per PR.

Agent sandboxes

Hand a fork to Claude. Let it break things. Destroy the fork after.

​How it works

​Set up the golden

​Fork it

​Patterns

​Per-PR previews

​Per-issue agent runs

​Bug repro

​FAQ

​Next

Per-PR preview URLs

Agent sandboxes

How it works

Set up the golden

Fork it

Patterns

Per-PR previews

Per-issue agent runs

Bug repro

FAQ

Next