> ## 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.

# Set up a golden

> A long-running VM with your app installed and running — the fork source for previews, fix, and deploy. Set this up first.

A **golden** is a long-running boxd VM with your app installed and serving on its
public `*.boxd.sh` URL. It's the **fork source** for everything else: per-PR
previews, the Claude fix loop, and deploy-on-push all work by *forking the
golden* (\~160 ms, app already running) and operating on the fork.

So this is **step one** — [`/boxd-setup-preview`](/preview-environments/per-pr-preview-urls),
[`/boxd-setup-fix`](/agents/fix-on-issue), and [`/boxd-setup-deploy`](/preview-environments/deploy-on-push)
all require a golden and will point you back here if you don't have one.

## What `boxd-setup-golden` does

It reads your repo the way a developer would (`AGENTS.md` / `CLAUDE.md`, `README`,
the manifests), then on a fresh VM it:

* installs what the app needs (the base image already ships Node, Python+uv, Go,
  Docker, `gh`, …) and runs your install/build,
* starts the app under something that survives a reboot (`pm2` / `systemd` /
  `docker compose`) and points the proxy at the app port,
* registers a headless-Chrome **`chrome-devtools` MCP** (so the fix loop can take
  before/after screenshots), and
* persists `gh` auth on the VM so forks can open PRs from inside.

When it's done, the VM *is* your golden — keep it running; forks are cheap and
inherit its live state.

## Set it up — two ways

The skill ships **both** to your laptop (with the boxd CLI) **and** baked into
every boxd VM image. Pick whichever fits:

<Tabs>
  <Tab title="From your laptop">
    Install the boxd CLI (this also drops the skills), then run the skill from the
    repo's directory:

    ```bash theme={"theme":"github-dark"}
    curl -fsSL https://boxd.sh/downloads/install.sh | sh
    ```

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

    It provisions a fresh VM and drives the install over the API (`boxd machine exec`),
    streaming progress back to you.
  </Tab>

  <Tab title="Inside the golden (in-VM)">
    Every boxd VM ships with Claude Code **and** these skills pre-installed. Create
    a VM and open an agent shell in it — then the VM you're on *becomes* the golden:

    ```bash theme={"theme":"github-dark"}
    boxd machine new my-golden
    boxd connect my-golden        # or: ssh my-golden.boxd
    ```

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

    No `boxd machine exec`, no API key, no staging — the agent installs and starts your app
    right there as the `boxd` user. This is the leaner path when you're already
    working inside a VM.
  </Tab>
</Tabs>

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

## Next — layer on the platform

Each of these forks this golden, so set the golden up first:

<Columns cols={3}>
  <Card title="Per-PR previews" 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">
    `/boxd-setup-preview` — comment `/boxd-preview`, get a forked URL.
  </Card>

  <Card title="Fix on issue" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/bug.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=793936d309dacb75c015231f4754aa3e" href="/agents/fix-on-issue" width="16" height="16" data-path="images/icons/bug.svg">
    `/boxd-setup-fix` — Claude fixes the issue in a fork, opens a PR.
  </Card>

  <Card title="Deploy on push" icon="https://mintcdn.com/azin/Ax1V0serIwQf0x_2/images/icons/rocket-2.svg?fit=max&auto=format&n=Ax1V0serIwQf0x_2&q=85&s=a1c1fe369620246bf94ebe0008da9032" href="/preview-environments/deploy-on-push" width="16" height="16" data-path="images/icons/rocket-2.svg">
    `/boxd-setup-deploy` — push to main, the golden redeploys.
  </Card>
</Columns>