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 managed 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. Everything on a template's page except editing the environment also works in a web browser; see team access and roles.

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. If the editing session can't start, the detail page will say so and the saved version will stay unchanged; choose Take control to try again.
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.

Editor threads load the skills in ~/.claude/skills and ~/.codex/skills, except any skill larger than 200 MB or with more than 5,000 files, including files it links to. Leaving those out keeps the editing machine quick to start, and projects created from the template will still include them.

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 in the desktop app 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 managed-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.

For a minute or two after a maintenance run publishes a new version, a new Managed-project devbox may still start from the previous version while boxes.dev prepares devboxes from the new one. A version you save from an editing session will apply to new devboxes as soon as it becomes current.

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. Managed 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 managed 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. Once the member starts typing a first message for a new devbox, boxes.dev checks their connections and files, then runs the team and member startup scripts before starting the agent. If a required member file or value is missing, the scripts and agent will run without it, and the desktop app will warn the member until they add it. Because the scripts can run for a draft the member never sends, keep the team script safe to run more than once. 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 managed 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, 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.

Agent guidance works differently in managed projects. Each new devbox in a managed project will get the template's current guidance, followed by any guidance the member saved in their own project settings, so a saved change will reach every managed project without editing each one. Independent projects get a copy when they're created.

To change a member's own project settings, such as guidance that repeats or conflicts with the template's, ask an agent on one of your boxes to edit that project. See Read and edit project and Team Template settings.

For integrations, connect the team's Tailscale, Slack, or Linear service before adding it as a requirement. AWS doesn't need a team connection, because members can use their own access keys if your team hasn't set up Company SSO. 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.

Team MCP connections

For a managed template, open MCPs on the template detail page. Adding, editing, or removing a definition will update existing and new managed projects without saving a new environment. Members can supply their own credentials and choose Codex, Claude, or both; they cannot edit or delete the team's definition. MCP connections are optional.

A matching personal connection will be adopted automatically with its existing sign-in and agent choices. Other personal MCPs remain available alongside the team's. See MCP connections for matching and account-wide behavior.

For an independent template, MCPs remain under Settings for new projects. New projects receive editable connection definitions without credentials, and later changes will not reach those copies.

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

Team agent settings

Open Agent settings on the template detail page to choose Claude and Codex settings for projects created from the template. For a managed template, a saved change will reach existing devboxes in managed projects within a minute, and members can add their own settings on top. For an independent template, new projects will receive a copy, and later changes won't reach existing projects. See Settings from a Team Template.

Team agent permissions

Open Agent permissions on the template detail page to choose the project agent permissions members' projects will use, such as creating devboxes and threads, messaging other agents, pausing and resuming agents, and folder access. Pause and resume agents defaults to Created from this devbox; wider choices will let agents control the project owner's own threads. Each project keeps its own permissions until you save these. For managed projects, choose a mode:

• Editable defaults: Managed projects will follow these permissions until a member changes one in Project settings. That member's change will stay as they set it when you change the template.
• Locked: every managed project will use these permissions, and members won't be able to change them in Project settings. Locking will replace any permissions members chose themselves. If you unlock later, everyone will keep the template's permissions until they change one.

The first time you save editable defaults for a template that already has managed projects, boxes.dev will ask whether to move those projects to these permissions or let each one keep its current permissions as the member's own choice. In both modes, members will still be able to change permissions on individual boxes. Independent projects will start with a copy of these permissions, and their owners will be able to change them.

If you give an agent's thread access to edit your Team Template, the agent can also change these permissions. It will ask you the same questions before its first save and before locking them.