Skip to main content
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.
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=<source ID>. instabox ls --meta instabox-fork-of=<ID> 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: 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.
  • 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.
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.
  • 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.
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.
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 to keep a machine’s state and start machines from it later, on any host.

Parallel forks

Try several approaches at once from one set-up machine.

Errors

fork_unavailable and every other error code.