> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Fork from a golden

> Warm copies of your fully-installed app, on demand, in ~160ms.

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

<Note color="#E05A6D">
  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.
</Note>

## 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, HTTPS domain, SSH port, 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 machine new`, open an agent shell, and the box you're on becomes the golden):

```text theme={"theme":"github-dark"}
/boxd-setup-golden
```

<Note color="#E05A6D">
  Claude Code only for now — [reach out](mailto:contact@boxd.sh) for Codex, OpenCode, or any other agent.
</Note>

Full walkthrough of both paths: [**Set up a golden**](/preview-environments/set-up-a-golden).

If you'd rather do it by hand:

```bash theme={"theme":"github-dark"}
boxd machine new yourapp-golden
ssh yourapp-golden.boxd
# 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

<Tabs>
  <Tab title="CLI">
    ```bash theme={"theme":"github-dark"}
    boxd machine fork yourapp-golden pr-482
    ```

    ```text theme={"theme":"github-dark"}
        name: pr-482
          id: 7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678
         url: pr-482.boxd.sh
      forked: yourapp-golden
        boot: 160ms
    ```

    Add `--json` for a parseable response:

    ```bash theme={"theme":"github-dark"}
    boxd machine fork yourapp-golden pr-482 --json
    ```

    ```json theme={"theme":"github-dark"}
    {
      "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"
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={"theme":"github-dark"}
    import { Boxd } from "@boxd-sh/sdk";

    const boxd = new Boxd();                                                  // reads BOXD_API_KEY
    const fork = await boxd.machines.fork("yourapp-golden", { name: "pr-482" });
    console.log(fork.access.url, fork.bootTimeMs, fork.source?.name);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":"github-dark"}
    from boxd import Boxd

    boxd = Boxd()                                              # reads BOXD_API_KEY
    fork = boxd.machines.fork("yourapp-golden", "pr-482")
    print(fork.access.url, fork.boot_time_ms, fork.source.name)
    ```
  </Tab>
</Tabs>

If you omit the 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](/preview-environments/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 machine 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](/agents/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.

```bash theme={"theme":"github-dark"}
boxd machine fork prod repro-bug-91
ssh repro-bug-91.boxd
# poke at it freely
boxd machine remove repro-bug-91 -y
```

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="How many forks can I run at once?">
    Up to 10 VMs per account total, extendable on request. Forks count toward this limit.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next

<Columns cols={2}>
  <Card title="Per-PR preview URLs" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/branching-paths-up.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=06ff61ff2b80a7adc15558368629f9bb" href="/preview-environments/per-pr-preview-urls" width="16" height="16" data-path="images/icons/branching-paths-up.svg">
    Wire forks into GitHub webhooks and ship a URL per PR.
  </Card>

  <Card title="Agent sandboxes" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/robot.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=e91e744c2d3cd5da053167486b6834bf" href="/agents/agent-sandboxes" width="16" height="16" data-path="images/icons/robot.svg">
    Hand a fork to Claude. Let it break things. Destroy the fork after.
  </Card>
</Columns>