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

> Copy a machine with its full disk state.

`fork` creates a new machine that is an exact copy of an existing one -- same filesystem, same installed packages, same data. The new machine gets its own name, HTTPS domain, and SSH port.

## Usage

```bash theme={"theme":"github-dark"}
boxd machine fork myapp
```

```
forking myapp-fork...
       name: myapp-fork
         id: 7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678
        url: myapp-fork.boxd.sh
forked from: myapp
       boot: 160ms
```

Specify a custom name:

```bash theme={"theme":"github-dark"}
boxd machine fork myapp myapp-v2
```

With `--json`:

```json theme={"theme":"github-dark"}
{
  "name": "myapp-fork",
  "vm_id": "7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678",
  "url": "myapp-fork.boxd.sh",
  "image": "default",
  "status": "running",
  "boot_time_ms": 160,
  "forked_from": "myapp"
}
```

The fork gets its own 100 GB disk, copied from the source machine.

<Warning>
  If the default name `{source}-fork` is already taken, the command fails. Use `--name` to pick a different name.
</Warning>

## Use cases

### Rollback

Fork before a risky change:

```bash theme={"theme":"github-dark"}
boxd machine fork myapp myapp-backup
# make changes to myapp...
# something broke?
boxd machine remove myapp -y
# myapp-backup still has the working state
```

### Experimentation

Try things without affecting your working machine:

```bash theme={"theme":"github-dark"}
boxd machine fork myapp experiment
# break things freely
boxd machine remove experiment -y
```

### Scaling

Need another instance of the same app:

```bash theme={"theme":"github-dark"}
boxd machine fork myapp myapp-2
```

Both machines run the same code and data from the moment of the fork. Changes after the fork are independent.

### Forking a shared org machine

If you fork a machine that's [shared with your organization](/organizations/share-a-vm), the fork is **private to you by default** — the org keeps paying, but only you can reach the copy, and your agent logins (Claude Code, Codex, OpenCode) work in it again right away. It's the clean way to take a shared golden machine and do focused, authenticated work on a copy without touching the shared original.

```bash theme={"theme":"github-dark"}
boxd machine fork staging                # private fork (org-billed, yours alone, logins restored)
boxd machine fork staging --shared       # keep the fork shared with the whole org
```

Forking a personal machine is unchanged — the fork stays personal.

## Golden images

A "golden image" is a long-running VM that has your app fully installed, configured, and running. You build it once -- clone the repo, install dependencies, run setup scripts, start the services -- then leave it running and fork from it whenever you need a warm copy.

Every fork inherits the full state -- code, dependencies, running services, data -- and boots in \~160ms. No rebuild, no reinstall, no waiting for `npm install` or container layers to pull.

Common patterns:

* **Per-PR previews.** Fork on every pull request, apply the branch's diff inside the fork, share the `*.boxd.sh` URL with reviewers. Destroy on merge.
* **Per-issue agent runs.** Fork the golden, hand it to Claude Code via `boxd machine exec`, let the agent fix the bug inside the fork. The PR closes, the fork goes away.
* **Sandbox copies.** Hand a fresh fork to anyone who wants to poke at the app without touching the source.
* **Reproducing bugs.** Fork production state, reproduce the issue safely, throw the fork away.

Forks boot in \~160ms with no setup, and auto-suspend keeps idle cost near zero on both the golden and its short-lived forks.

The `/boxd-setup-golden` and `/boxd-setup-fix` skills wire this whole loop up for you. See [Skills](/reference/skills).

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