Startup, teardown, and maintenance

Use a startup script to prepare each new devbox, such as updating its Git checkout, and a teardown script to clean up resources when a devbox is destroyed. Template box maintenance serves a different purpose: it updates the saved environment that future devboxes will start from, for example by installing dependencies after a lockfile changes.

A new devbox begins with the files in the project's saved environment — the latest Template box snapshot, or a Member project's current Team Template version. An optional startup script can pull newer commits automatically; you or your agent can also update the checkout manually.

Configure startup and teardown

1. Open Project settings → Devbox lifecycle → New devbox defaults in the desktop app.
2. Enter shell commands in Startup Script and set its Timeout. The default is 60 seconds; the allowed range is 1–120 seconds.
3. If the project needs cleanup before a devbox is destroyed, enter those commands in Teardown Script. Its timeout defaults to 30 seconds and allows the same 1–120 seconds.
4. Choose Save. boxes.dev will store the commands as project settings; it will not create script files for you.

Both scripts run in a noninteractive shell. In an independent project, they run in the project root. In a Member project, startup runs inside the sole repository, or from the project root when there are zero or several repositories; teardown still runs from the project root. Name a repository folder in commands when needed (git -C sandbox pull). Review any commands that change external services before saving them. Destruction will continue even if teardown fails, so do not rely on teardown as the only way to save important work.

A Member project starts with the Team Template's default startup and teardown scripts; the copies here belong to your project, and editing them changes only your own devboxes. Member devboxes also run the team's own startup and teardown stages, which team admins manage in Maintain a Team Template.

Configure agent guidance, startup commands, and teardown commands in Project settings. Select the image to enlarge it.

When startup runs

For an independent project, boxes.dev can prepare a new devbox while you type the first prompt and run startup before you press Send. A Member project can also have a prepared devbox waiting, but its team and member startup scripts run after Send, once your connections and files are ready. The team script runs first, so its duration adds to the wait for your first turn.

Make startup scripts safe to repeat: preparation can happen more than once — boxes.dev will discard a prepared devbox and prepare another if the settings change or a draft is abandoned. Discarding that devbox does not undo changes the script made to external services; undo those changes yourself when needed.

Managed environment files, project storage, Git access, AWS credentials, and configured outbound networking are prepared before startup. Tailscale connects after Send, so the script should not depend on Tailscale access.

On any one devbox, startup runs once before its first agent turn. Waking it or starting another thread on it will not rerun the scripts.

If startup fails or times out, the devbox will still start and the thread will show a warning; inspect the output shown with it and fix the problem before relying on your app. A corrected script will apply to the next devbox — on this one, run the needed commands yourself in Terminal or ask the agent. Dismissing the warning acknowledges that result across your devices; a later failure can still produce a new warning.

Maintain your Template box

For an independent project with its own Template box, configure maintenance on the Template box page:

1. Choose Set up maintenance.
2. Enter the commands that update your environment and set a timeout of up to eight minutes. The script will run as the boxes user in the project root.
3. Save the settings, then choose Run now to test them.

If the script succeeds, boxes.dev will save a new snapshot for future devboxes. Keep interactive work off the Template box while a maintenance run is expected: the script will change that machine and may interrupt someone using it.

If your independent project was created from a Team Template that had maintenance configured, it arrived with its own copy of that script and schedule. The copy belongs to your project — manage it here, and later Team Template changes won't update it.

Configure a maintenance script and its schedule for the Template box. Select the image to enlarge it.

Run maintenance automatically

Choose an optional schedule: every 6 hours, every 12 hours, nightly, or weekly. With GitHub connected, you can also watch files or directories in the project's own repositories. A lockfile watch, for example, can trigger a script that pulls the changed lockfile and installs the updated dependencies — the watch only requests the run, so the script itself has to fetch the change.

Enter exact repository-relative paths, one per line. Watches use each repository's default branch; globs and custom branches are not supported. Maintenance can watch up to ten repositories and fifty total paths.

Adding or editing a watch starts tracking from the repository's current state without immediately running maintenance. After a push, boxes.dev checks whether the watched files have changed; a change reverted before that check will not trigger a run.

Use trigger details in your script

Multi-repository projects use one script and one snapshot per run. For a GitHub-triggered run, your script can read the JSON file named by BOXES_TEMPLATE_MAINTENANCE_CONTEXT_FILE; it lists the triggering repositories, their inspected commits, and the watched paths that changed.

Check the result or recover a failure

If the script fails, times out, or is canceled, boxes.dev will not take a snapshot. Changes the script already made will remain on the live Template box; inspect them before retrying.

The page shows output and recent run history. Cancel run stops a queued or running script; it cannot cancel snapshot creation after a successful script. If only the snapshot failed, use its retry instead of rerunning the script.

Maintenance and snapshot creation do not run at the same time. If a GitHub watch reports an access problem, follow its reconnect or repository-access instructions. Retry other watch errors and contact support if they persist.

Team Template maintenance

A Team Template — the shared starting environment a team admin maintains — has its own maintenance workflow: it updates the team's clean saved environment and publishes a verified saved version. Member projects do not run Template box maintenance of their own. Team admins manage all of this in Maintain a Team Template.

Ask an agent to configure scripts

You can also ask an agent on your independent project's Template box to edit scripts and maintenance watches — choose New thread on Template box on the Template box page to start one. Enable Edit devbox lifecycle or Edit template maintenance in the thread header's Agent permissions, according to the task; they are separate permissions. To schedule an agent conversation instead of a shell script, use an automation.