Skip to main content
A sandbox is ready when the API reports its state as ready, idle or running. From then on, commands, SSH and prompts work at once. boat new, boat fork and boat resume return when the sandbox is ready and a first command works. In a script, you can run your next command right after them.

​
Ready, in one table

The CLI and the dashboard show provisioned as starting. At provisioned, the machine is up, but Boat still applies your environment, secrets and repositories.
A command that you send while the sandbox starts does not fail. The API holds it for up to 60 seconds and runs it when the sandbox is ready. After 60 seconds, it answers 409 sandbox_starting. Send it again. A command sent to a stopped sandbox, or to one in error, fails with 409 sandbox_not_ready. Resume the sandbox first.

​
What works at ready

​
What comes a few seconds after ready

On a resume, a fork or a deploy from a named snapshot, Boat restores in the background. These parts come after ready: A new sandbox, made with boat new and no --from, restores nothing. Docker and services start with the machine. Some users see the first outbound connection fail in the first second after ready. Retry a failed first connection.

​
Wait in a script

The common case needs no wait. Run your command after boat new or boat resume:
Wait for Docker:
Wait for a systemd service:
Wait until every file is downloaded:
With the API, poll GET /sandboxes/{sandboxId} and read sandbox.state and sandbox.hydrated. Or subscribe to the sandbox.ready and sandbox.hydrated webhooks. Wait for a stop: boat stop returns at stopping. Poll boat info until the state is stopped. Read Wait for the stop in a script.

​
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. 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 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.
The time to a working app depends on what your app reads first. Large first reads, Docker images and services that start late add seconds. The next section makes the first start faster.

​
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:
1

Start the sandbox from a snapshot

Resume a stopped sandbox, or deploy one from the named snapshot that you want to update. A new, empty sandbox has nothing to record.
2

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.
3

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 named snapshot does not have this run.
Each run adds to the list. It does not replace it. The newest run counts most. Each time you repeat these steps, the named snapshot starts a little faster. The list holds the first 5,000 paths.