Maintain a Team Template

Update a Team Template when teammates need a new shared dependency, tool, or repository checkout. As a team admin, you can edit the environment yourself and save a new version, or automate recurring updates with maintenance. Future independent projects and new devboxes in Member projects will use the new version; existing devboxes will keep their files.

Scripts and project defaults save separately from environment versions; the sections at the end cover when each change applies. To pause or resume new project creation from a template, see team access and roles; to archive or restore a template, see rename, archive, or restore.

Edit the environment

1. In the desktop project selector, open Team Templates and select the template. From any project made from the template, you can also open Project settings and choose Open Team Template. Then choose Take control on the template's detail page. If the template is archived, restore it first under Template settings.
2. Use Terminal, Files, Git, Browser, or a Codex/Claude thread to prepare and test the environment. Each template allows one admin editing session at a time.
3. Review the files members will receive, including credentials in environment files, databases, and shell history, and remove anything they should not receive. Saving removes boxes.dev-managed private agent state, but cannot identify credentials you added yourself.
4. Finish active agent work, then choose Save and close and confirm. Wait for the new version to be ready on the detail page; the previous version will remain current until cleanup, a startup check, and the save succeed.

If your team needs to remove additional files on every save, configure Template environment → Cleanup before saving. The script will run in /home/boxes without network access; a nonzero exit will stop the save.

To pause your work, open the machine's status in the editor titlebar and put it to sleep. It will retain your unsaved files; choose Continue editing when you return. Closing the desktop app or automatic sleep after inactivity also keeps the editing session assigned to you.

To abandon the edit, choose Discard changes and type DISCARD to confirm. This will permanently remove the session's unsaved files and leave the current saved version unchanged.

The editing session's Codex and Claude threads are private to their author. You can restore a saved thread during a later editing session; ask the agent to inspect the current checkout before continuing, since files may have changed since that conversation.

The editing machine has managed GitHub access for the template's selected repositories. It supports fetch, pull, and push, except pushes that change GitHub Actions workflow files. Use your own authorized Git access for those changes, and remove any credentials you install before saving.

The Environment section shows the current version and the controls for editing and maintenance. Select the image to enlarge it.

Resolve another admin's sleeping edit

If another admin holds a sleeping editing session, you cannot open it to inspect or continue their work, so the simplest path is to ask them to finish and save or discard it themselves. If you need the template now, open its detail page and choose Resolve, then decide whether to save their work as the next version or discard it permanently. boxes.dev will then create a fresh editing session for you.

Use or remove an older version

To put future projects and Member-project devboxes back on an older environment:

1. Save or discard any open editing session.
2. Open Template environment → Previous versions.
3. Find a ready version and choose Restore this version.

The current version will stay available until the selected version is ready. If preparation fails, use the retry action shown beside the failure. Your next save will still receive the next version number.

Removing an inactive version requires a reason. Removal will prevent new work from starting from that version and cancel project creation still using it; existing independent projects will keep their own Template boxes.

Automate maintenance

Use maintenance for recurring updates, such as fetching repository changes and installing dependencies. Under Template environment → Maintenance, configure a script and schedule, and optionally add GitHub file or directory watches that request a run when those paths change. Choose Run now to request an immediate run.

A maintenance run starts from the current saved environment and runs your script with temporary GitHub access to the template's tracked repositories. A successful run will clean and validate the result, then publish it as a new saved version; the previous version stays current until then. If the script fails, boxes.dev will discard the changed environment and keep the previous version. Runs will wait while an editing session is open, without changing that admin's files, and multiple pending triggers combine into one run.

If maintenance needs attention, the fix appears on the template's detail page under Maintenance:

• If the script succeeded but saving failed, use Retry save and Discard result when they are offered; retrying the save does not rerun the script.
• If repository access was lost, choose Open GitHub settings and restore access. Then choose Refresh repository access on the failure before retrying maintenance. The refresh covers repositories the template already tracks; it does not add repositories.

An admin's agent in the editing session can also configure maintenance with dvb-onbox project maintenance get and apply. Saving that configuration will not run the script immediately.

If the Maintenance section asks you to restore the template's saved version first — a one-time step for templates saved before maintenance was available — use Previous versions to restore it, then return to Maintenance.

Maintenance reaches the two project types differently. An independent project receives its own copy of the maintenance settings when created, without previous run history; the schedule starts at its next occurrence, file watches start tracking changes from the new project's initial files, and the copy can keep updating that project's own Template box afterward. Member projects do not copy or run template maintenance at all — their future devboxes simply use the team's current saved files.

Change scripts and project settings

Open When a new devbox is created to configure startup scripts. Choose Add script or Edit script beside a stage, then Save script. Expand When a devbox is destroyed for teardown scripts. Saving a script records it; it will not run the script or save a new environment version.

In a Member project with exactly one repository, both startup scripts run inside that repository. With zero or several repositories, they run from the project root, normally /home/boxes; name the repository folder in commands that need it, for example git -C sandbox fetch origin. Teardown scripts run from the project root in either case. Check Runs in beside each script before editing it.

boxes.dev can prepare a devbox for a member ahead of time. When the member sends their first message, boxes.dev checks their connections and files, then runs the team and member startup scripts before starting the agent. Both scripts can use that member's credentials and files, so team admins must review the team script with that access in mind. The stages, in order:

The team stages apply only to Member projects; independent projects start from their own Template boxes and run their own member scripts, edited in each project's settings — see Startup, teardown, and maintenance. Unused or failed devbox preparations may skip member teardown.

If either startup script fails or times out, the devbox will show a warning and continue to the next script and the agent. Both results remain available if both scripts fail, and other members can still create devboxes. Open the warning's details to inspect or copy its output. Team admins can choose Review startup script; other members should send the details to an admin.

A saved correction will apply to future devboxes. On the affected devbox, run the needed commands in Terminal or ask the agent to help. Waking it or opening another thread will not rerun startup. A teardown failure will not stop destruction; team teardown failures remain on the template's detail page.

Team startup runs after member connections and files are ready, followed by member startup. Select the image to enlarge it.

Defaults copied to new projects

To change other defaults, open Settings for new projects and save the relevant setting. It contains agent guidance, a first-prompt prefix, Git and port behavior, Project URLs, MCP connection definitions, initial integrations, and setup instructions. Each change will apply to new projects immediately, and existing projects of either kind will keep their copied defaults; team scripts follow the rules above, and environment and member-file definitions follow Required member files and values.

For integrations, connect the team's AWS, Tailscale, Slack, or Linear service before adding it as a requirement. Required integrations must be connected before the member can finish initial setup; Recommended integrations can be left for later. Setup instructions provide the prompt for an optional agent setup thread and apply only to independent projects.

New projects will receive fresh Project URL hostnames. Inherited MCP definitions contain connection details only, never credentials; each member signs in or adds their own key in the new project.

See Start from a Team Template for how members finish this stage, including reusing or renaming an inherited MCP connection.