Skip to main content

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 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, IP, and HTTPS domain.

​
Usage

ssh boxd.sh fork myapp

forking myapp-fork...
       name: myapp-fork
         id: 7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678
        url: myapp-fork.boxd.sh
forked from: myapp
       boot: 1.8s
Specify a custom name: 
ssh boxd.sh fork myapp --name=myapp-v2
With --json: 
{
  "name": "myapp-fork",
  "vm_id": "7a3f8c12-bb41-4e09-a5d2-91c3e4f0d678",
  "url": "myapp-fork.boxd.sh",
  "image": "default",
  "status": "running",
  "boot_time_ms": 1800,
  "forked_from": "myapp"
}
The fork gets its own 100 GB disk, copied from the source machine. The fork is placed on the same worker as the source machine.
If the default name {source}-fork is already taken, the command fails. Use --name to pick a different name.

​
Use cases

​
Rollback

Fork before a risky change: 
ssh boxd.sh fork myapp --name=myapp-backup
# make changes to myapp...
# something broke?
ssh boxd.sh destroy myapp
# myapp-backup still has the working state

​
Experimentation

Try things without affecting your working machine: 
ssh boxd.sh fork myapp --name=experiment
# break things freely
ssh boxd.sh destroy experiment

​
Scaling

Need another instance of the same app: 
ssh boxd.sh fork myapp --name=myapp-2
Both machines run the same code and data from the moment of the fork. Changes after the fork are independent.

​
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 ~1.8s. 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 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 land on the same worker as the golden, so there’s no cross-network 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-on-issue skills wire this whole loop up for you. See Skills.