Update your Template box and snapshots
On this page
Your Template box is the cloud machine where you prepare the environment that future devboxes will start from. After changing its tools, dependencies, or local data, save a snapshot so new devboxes will start with those changes. For example, install a new dependency once on the Template box, test your app, and snapshot the result.
These steps apply to an independent project with its own Template box. If you have a Member project, there is no Template box: a team admin needs to update the Team Template that supplies your devboxes.
Make the environment change
- Select Template box in the desktop sidebar. Open its Terminal or Files, or choose New thread on Template box to have an agent on that machine make the change.
- Make the change with the tools your project expects — install the dependency, update the setup file, or load the local database state.
- Start your app and test a page, command, or other workflow that depends on the change.
Keep unrelated code changes out of this work: files in the snapshot, including uncommitted edits, will reach every future devbox. If the agent needs a credential, provide it through Environment files or the file editor instead of pasting it into the conversation.
If you developed the change on a devbox instead, apply it to the Template box before taking a snapshot — run the same commands there, or ask a Template box agent to. A snapshot saves the Template box's own state, and work left on a devbox stays there.
Take a snapshot
Before saving, review files for secrets or data that future devboxes should not receive.
With the Template box selected, open its machine status menu and choose New snapshot, or run this in its Terminal:
dvb-onbox snapshot
Both paths do the same thing, and the command works only on the Template box. The machine status will show Snapshotting during the brief capture, and the new snapshot will join the history on the Template box page; the command also waits and reports the result. If a Codex or Claude agent is working there when capture starts, boxes.dev pauses it during capture and resumes it afterward.
A snapshot preserves files — including the Git checkout as it stands — along with local development data, agent settings, and the agents' saved conversation files. New devboxes start their own processes: they will not continue an app that was running on the Template box, and the copied conversation files are not a running copy of the agent. Use a startup script for commands that need to run on each new devbox, such as pulling commits newer than the snapshot.
Know which changes need a snapshot
As a rule, configuration you set up through boxes.dev syncs to machines on its own, while changes made directly on the Template box's disk reach future devboxes only through a snapshot.
So take a new snapshot after changing installed tools, setup files, local database state, or plugins and MCP configuration managed directly on the Template box. Copied plugin files may still require a separate sign-in on a new devbox. Settings managed by boxes.dev, such as environment values, project MCP connections, managed plugins, and AWS access, reach new devboxes without a new snapshot, and plugins labeled Synced by Codex follow your Codex account and workspace. Old snapshots in the history can still contain earlier credential files; revoke credentials at their provider if those copies should no longer work.
Adding a repository has its own automatic snapshot: a successful Add from GitHub or Review new repositories on the Template box takes one for you. Cloning a repository manually does not, until you complete that review. See Add a repository for future devboxes. A successful maintenance run also saves its own snapshot.
Shared project storage at /project is the
same folder across the project's machines; snapshots do not copy or replace
it.
Check a new devbox
Choose New devbox + thread, select your agent, and send a request to start and test your app. The new machine will begin with the files saved in the latest snapshot; check the important tools and the workflow you tested on the Template box.
Existing devboxes keep their own files — a new snapshot will not update them. To get the change onto a devbox you already have, run the same commands there or ask its agent; otherwise finish that work and start your next devbox from the new snapshot.
In the mobile app, creating a devbox can also offer a choice between the latest saved snapshot and a fresh snapshot taken first.
Use Git to move finished code between machines. A snapshot saves the Template box's environment; it does not merge work from your devboxes.