> ## Documentation Index > Fetch the complete documentation index at: https://instabox.sh/docs/llms.txt > Use this file to discover all available pages before exploring further. # Fork > Copy a machine's disks into new machines on its host, in seconds. Fork a machine to get a copy of it now, with the same files, template, and size. The copy is made on the source's host, without a snapshot, and takes about as long as a create. ```bash theme={null} instabox fork dev --name dev2 instabox fork dev --name try --count 3 --json # try-1 to try-3 ``` `fork` (or `clone`) copies a running or stopped machine into one new machine, or up to 5 with `--count`. The new machines have the source's template and size unless you pass `--vcpus` and `--mem-mib`. The command waits until they run. Over the API, send `POST /v1/machines/{id}/fork`. ## What a fork is A fork is a copy-on-write copy of the source's disks: the system disk and `/data`. Memory and running programs are not copied. The new machine starts from the copied disks, like a machine that was stopped and started again. Services enabled as systemd units start on their own. Start anything else again. The source machine is not changed and keeps running. ## What the new machine gets * The source's files on the system disk and in `/data`, as they were at the fork. * The template and the size. * The source's kernel, if the source is pinned to one. Otherwise the fork starts on the host's current default kernel, which can differ from the one the source runs. * The environment variables. * The Secret selection. Each Secret gets a new placeholder in the new machine. * Its own hostname, machine ID, and SSH host keys. * The label `instabox-fork-of=`. `instabox ls --meta instabox-fork-of=` lists a machine's forks. A fork does not get the source's published ports. Publish them again with `instabox port publish`. ## Keep or change the source's settings A fork keeps the source's auto-pause, max runtime, labels, and delete time. To change one, pass the flag for it: | Setting | CLI flag | API field | | - | - | - | | Auto-pause | `--auto-suspend` | `autoSuspendAfterSeconds` | | Max runtime | `--max-run-minutes` | `maxRunMinutes` | | Labels (added to the source's) | `--meta` | `metadata` | | Delete time | `--delete-after` | `deleteAfterSeconds` | The delete time is the same moment as the source's. A source deleted in 2 hours gives forks deleted in 2 hours. A source due for deletion within a minute is refused unless you pass `--delete-after`. Your plan's limits apply to these values as they do on `create`, whether you set them or the fork kept them from the source. A kept value that your plan does not allow is refused, nothing is created, and the error names the flag to pass instead. ## Fork many machines at once * Forks of one source wait for each other only while their disks are copied, a moment each. Then they start in parallel. Forks of different sources do not wait for each other. * Each new machine counts toward your plan's running machines and machine starts a minute. See [Limits](https://instabox.sh/docs/account/limits.md). * `fork` waits out the start limit, for as long as the server's `Retry-After` says, up to 5 times. * `fork` does not wait for the running limit. When your workspace cannot run `--count` more machines, `fork` creates none, says how many fit, and exits with code 5. Retry with that `--count`, or stop or pause machines first. > [accordion] Fork a machine that is writing > > Before the copy, the source's file systems are frozen, which writes its cached files to disk. So the > copy has every write that a program made before the fork, synced or not, and it mounts normally. > Data that a program still holds in its own memory is not in the copy. A file that was half written is > half written in the copy. The source pauses for a moment while its disks are copied, and for a few > seconds under heavy writes. A fork through a snapshot (below) copies the disks the same way. > [accordion] Source state > > * **Running or stopped:** the fork works. > * **Paused:** refused with `409 fork_unavailable`, which is not retryable. Resume the machine first. > A paused machine cannot be stopped. > * **Resuming:** refused with `409 operation_conflict`, which is retryable. Try again once it runs. > * **Just stopped:** the fork waits until the stop has saved the disks, so it can take a few seconds > longer. If the save is still running after that wait, the fork is refused with > `409 operation_conflict`, which is retryable. > > A fork whose copy has started finishes, even if you delete the source. If you delete the source > before the copy starts, the fork fails with `fork_unavailable` and nothing is created. A fork of a > fork works too. > [accordion] A source host under maintenance or full > > The new machine is placed on the source's host. If that host is under maintenance or full, nothing > is created and the answer is a retryable `409 fork_unavailable`. Its `reason` is > `source_host_unavailable` (maintenance) or `source_host_full` (no room). `instabox fork` then uses a > snapshot, whose copies can start on any host. To fork natively instead, stop and start the source to > move it to another host, then fork again. > [accordion] When the CLI uses a snapshot instead > > Sometimes the server cannot fork natively: an older server, a stopped machine whose files are only > in storage (no host), a host that cannot make the copy, or a source host that is under maintenance or > full. Then `instabox fork` says so on stderr and saves a snapshot and creates the copies from it, as > `--keep-snapshot` always does. This path is different: > > * It takes longer: a snapshot save, then a create from it. > * The copies are ordinary creates, so they can start on any host. > * The copies do not get the source's environment variables. They do get its size, Secret selection, > auto-pause, max runtime (on a paid plan), labels, and delete time, as a native fork does. > * A running source is saved with a live snapshot, which copies the disks as a native fork does. A > server without live snapshots refuses it. Stop the source, then fork. > * The snapshot is deleted afterwards, also on error or Ctrl-C, unless you pass `--keep-snapshot`. > > A paused source is refused on both paths. ## Fork or snapshot Fork for a copy now, on the same host. Save a [snapshot](https://instabox.sh/docs/machines/snapshots.md) to keep a machine's state and start machines from it later, on any host. > [card] [Parallel forks](https://instabox.sh/docs/use-cases/parallel-forks.md) > > Try several approaches at once from one set-up machine. > [card] [Errors](https://instabox.sh/docs/reference/errors.md) > > `fork_unavailable` and every other error code.