Skip to main content
When many boxes need the same stack pre-installed, build it once and fork it, instead of installing on every fresh box.
  1. Create a box and install everything: runtimes, packages, your app or daemon.
  2. Stop it: box stop <template-id>. Its snapshot is now your template.
  3. For each new box: box fork <template-id>. Forks are usable in a few seconds, at roughly constant cost regardless of how much the template holds.
box new                          # install your stack, then:
box stop bx_template
box fork bx_template
box fork bx_template --no-env    # fork for one of your own users

curl -sS -X POST "$BOX_API_BASE/boxes/bx_template/fork" \
  -H "Authorization: Bearer $BOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"noEnv":true,"env":{"TENANT_ID":"acme"}}'

const forked = await box.fork({
  boxId: "bx_template",
  forkRequest: { noEnv: true, env: { TENANT_ID: "acme" } },
});

forked = box.fork("bx_template", ForkRequest(no_env=True, env={"TENANT_ID": "acme"}))
Forks inherit the whole filesystem: files, installed packages, enabled systemd services, Docker named volumes. Hand-run processes are not forked; start them in the fork. A fork inherits the source’s per-box env unless the fork request passes its own (env on fork is API and SDK only), and a fork of a no-env box is always no-env.

​
Updating the template

Keep the template stopped. To publish a new version: resume it, update the stack, stop it again. Forks always take the latest snapshot.

​
Warm the template for faster first boots

A box learns the read order of your startup and prefetches those files first on the next restore. Forks inherit what the template learned: before publishing, resume the template, run your app’s normal boot once, then stop it.