> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Resume and fork

> Get a stopped sandbox back, or make a copy of a sandbox. How fast a sandbox comes back from a snapshot.

Resume and fork both start a machine from the latest snapshot of a sandbox.

| | Resume | Fork |
| - | - | - |
| You get | The same sandbox, with the same id | A new sandbox, with a new id |
| The source sandbox | Is the sandbox | Keeps running. Boat does not change it |
| Use it to | Continue your work after a stop | Try something risky, start a second branch of work, give one sandbox to each of your users |

If you fork the same sandbox again and again, make it a [template](/snapshots/templates) instead.

## Resume

A resume brings a stopped sandbox back on a new machine. The sandbox keeps its id and its disk.

<CodeGroup>
  ```bash CLI theme={null}
  boat resume bx_f7k2q9hd
  boat resume bx_f7k2q9hd --type large      # different machine size
  boat resume bx_f7k2q9hd --ttl 7200        # new lifetime, in seconds
  boat resume bx_f7k2q9hd --no-auto-stop    # runs until you stop it
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/resume" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"type":"large","ttlSeconds":7200}'
  ```

  ```ts TypeScript theme={null}
  await sandbox.resume({
    sandboxId: "bx_f7k2q9hd",
    type: "large", ttlSeconds: 7200,
  });
  ```

  ```python Python theme={null}
  sandbox.resume(sandbox_id="bx_f7k2q9hd", resume_request=ResumeRequest(type="large", ttl_seconds=7200))
  ```
</CodeGroup>

* A resume needs a complete snapshot. You get one when you stop the sandbox with `boat stop`.
* You can resume on a smaller machine. If the sandbox has more data than the smaller machine can hold, Boat refuses the resume and does not change the sandbox. Read [Machines](/machines).
* If you do not send `ttlSeconds`, the sandbox keeps its current lifetime.
* To turn auto-stop off, send `null` (`--no-auto-stop`).

## Fork

A fork copies a sandbox into a new sandbox. Boat uses the latest snapshot of the source. The source keeps running, and Boat does not change it.

<CodeGroup>
  ```bash CLI theme={null}
  boat fork bx_f7k2q9hd
  boat fork bx_f7k2q9hd --type small
  boat fork bx_f7k2q9hd --ttl 600         # lifetime for the fork, in seconds
  boat fork bx_f7k2q9hd --no-auto-stop    # runs until you stop it
  ```

  ```bash curl theme={null}
  curl -sS -X POST "$BOAT_API_BASE/sandboxes/bx_f7k2q9hd/fork" \
    -H "Authorization: Bearer $BOAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"type":"small","ttlSeconds":600}'
  ```

  ```ts TypeScript theme={null}
  const forked = await sandbox.fork({
    sandboxId: "bx_f7k2q9hd",
    type: "small", ttlSeconds: 600,
  });
  ```

  ```python Python theme={null}
  forked = sandbox.fork(sandbox_id="bx_f7k2q9hd", fork_request=ForkRequest(type="small", ttl_seconds=600))
  ```
</CodeGroup>

What the fork gets from the source:

* The whole disk.
* The per-sandbox variables of the source. If you send your own `env`, the fork uses yours.
* The exact environment version of the source. Read [Environments](/environments).

What the fork does not get:

* The lifetime of the source. A fork stops after 1 hour by default, even if the source has auto-stop turned off. To change this, send `ttlSeconds` or use `--no-auto-stop`.

## How fast a sandbox comes back

A resume, a fork or a deploy is ready in **a few seconds, whatever the size of the disk**. You see all your files at once. Boat downloads their content in the background.

| What | What happens |
| - | - |
| Every resume, fork and deploy | It runs on a new machine. Boat downloads your files again in the background, even if the sandbox had all its files before the stop. `hydrated` is `false` until the download ends. |
| A file that is not downloaded yet | When you open or read it, Boat gets that file first. Then you get the right bytes. |
| End of the download | `hydrated` becomes `true`, `hydratedAt` is set, and the `sandbox.hydrated` webhook fires. |
| Files of the machine image | They are already on every machine. Boat downloads only the files that differ from the image. |
| Paths in `.boxignore` | Boat does not save them, so it does not download them. Read [Leave files out](/snapshots/whats-saved#leave-files-out-with-boxignore). |

A restore does not need space for a second copy of your disk. Boat removes each downloaded part when it has used it. The [restore limits of each machine](/machines) count the size of your files, not the smaller download size.

Permissions, owners, times and extended attributes come back with your files and folders. Two of them come back later:

* **Extended attributes of a file** come back when the content of that file arrives. Folders have theirs from the start.
* **Folder modification times** come back when the download ends. Each new file in a folder changes the time of that folder, so Boat sets the time last.

## Make the first start faster

When a sandbox starts from a snapshot, it records which files open first. It keeps this list in `.ascii/playbook.json`. At the next start, Boat downloads these files first. Your app then works before the rest of the disk arrives. `ready` does not wait for these files.

The list is a normal file. It goes into the snapshot, so forks and deploys get it too.

The list is recorded **only while a sandbox starts from a snapshot**. Do these steps in this order:

<Steps>
  <Step title="Start the sandbox from a snapshot">
    Resume a stopped sandbox, or deploy one from the template that you want to update. A new, empty sandbox has nothing to record.

    ```bash theme={null}
    boat resume bx_f7k2q9hd
    ```
  </Step>

  <Step title="Start your app at once">
    Run your normal start command at once, while files still download. Boat records each file that your app opens, in order. Boat does not record files that open after the download ends.

    ```bash theme={null}
    boat exec bx_f7k2q9hd "cd my-repo && npm run dev"
    ```
  </Step>

  <Step title="Wait for the download to end, then save">
    Boat writes the list when the download ends. Save after that. If you save too early, the template does not have this run.

    ```bash theme={null}
    boat snapshot bx_f7k2q9hd web-stack
    ```
  </Step>
</Steps>

Each run adds to the list. It does not replace it. The newest run counts most. Each time you repeat these steps, the template starts a little faster. The list holds the first 5,000 paths.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.