Create and publish a Team Template

Prepare a Team Template once so teammates can start projects with repositories, dependencies, and tools already installed. You'll create the template, prepare its environment on a private editing machine, and save a first version for members to use.

You need the desktop app and team admin access. If you include GitHub repositories, the flow will ask you to connect your GitHub account and grant access to the ones you select.

Choose a starting point

First decide which kind of project the template should create for members. By default, each new project is independent, with its own Template box copied from your saved version. A template can instead create Member projects, whose devboxes always start from the team's current saved version — but that switch is one-way, and it requires every template repository to use a standard github.com remote, a local repository path, or no remote. Compare the two in Choose how to share an environment. You'll enable Member projects after the first save; choosing repositories with that plan in mind now avoids rework.

1. Open the project selector, then Team Templates → View all Team Templates.
2. Select New Team Template.
3. Choose one or more GitHub repositories, or create a new repository in the setup flow. Choose Start empty if you don't need GitHub repositories.
4. Enter a name and description and choose Machine size. The size is fixed after creation and will be inherited by every project made from the template; keep separate templates for setups that need different sizes.
5. For GitHub setup, review each repository's folder under /home/boxes (the editing machine's home directory), then choose Prepare Team Template. For an empty template, choose Create Team Template.

The Team Templates collection, with New Team Template and each template's saved version and status. Select the image to enlarge it.

boxes.dev will prepare a private editing machine — the cloud machine where you get the environment ready before saving it — and clone the selected repositories onto it. Cloning uses temporary GitHub access limited to those repositories; you don't need to register an SSH key. If preparation is interrupted, continue from the template's card or detail page. Creating the template does not make it available for new projects yet; members can use it only after you save its first version.

Give the Team Template a name and description your teammates will recognize. Select the image to enlarge it.

Prepare the environment

Open the template's detail page and choose Take control to start an editing session. Only one admin can edit a particular template at a time, so taking control never opens another admin's work. The editor opens with the editing machine's terminal in front.

Run commands in Terminal yourself, or choose the new-thread control in the thread list and start a Codex or Claude thread; the thread runs directly on the editing machine, so the agent can install dependencies, configure tools, and run your app there. You can keep several threads against the same checkout, and they are private to you. Use the Files, Git, and Browser tools to test your app and inspect the resulting changes before saving.

Ask the agent to check tool versions and the project's normal build or test command from a new terminal session. Confirm that configured startup commands launch any required services without temporary shell changes. Before saving, read its summary of checks that passed and anything still blocked by missing access or secrets.

Files retained in the saved environment will be copied into projects and devboxes created from that version. Before saving, review environment files, private keys, local databases, shell history, logs, and caches, and remove anything teammates should not receive — including credentials you added for your own testing. Saving removes boxes.dev-managed agent logins and private sessions, but it cannot identify credentials you installed yourself. For configuration each teammate should supply personally, define required member files and values rather than leaving your own in the environment. For a walkthrough with screenshots and cleanup examples, use the public Team Template setup guide.

To pause your work, open the machine's status in the editor titlebar and put it to sleep; choose Continue editing when you return, and your unsaved files will still be there. The session stays assigned to you even if you close the desktop app or the machine sleeps on its own.

Save and verify a version

1. Finish testing the app and reviewing the files that members will receive.
2. Let active agent work finish, then choose Save and close and review the confirmation.
3. Confirm the save and wait on the detail page for the new version to be ready. boxes.dev removes its managed agent state, runs the team's Cleanup before saving script if one is configured, and checks that the cleaned environment starts from its saved files.

Running processes will not continue in members' new machines. If members' devboxes should start your app or services, add a startup script under When a new devbox is created; see Maintain a Team Template.

For later saves, the previous version will remain available until the new one is ready. If saving fails, follow the recovery action beside the error on the detail page.

Discard changes will permanently remove unsaved work from the editing session; a saved version, if one exists, will remain unchanged. Confirm by typing DISCARD. Before the first save, reopening a discarded GitHub-backed template will recreate clean clones of the originally selected repositories; other unsaved files cannot be recovered.

Configure project defaults

On the detail page, open Settings for new projects to choose what members' projects will receive: agent guidance, a first-prompt prefix (text added to the start of a new thread's first prompt), Git and port behavior, Project URLs, MCP connection definitions, initial integrations, and optional setup instructions — the prompt for the setup agent thread an independent project can run after creation. Each setting saves separately and applies to projects created afterward. Settings and the environment also save independently of each other: saving an environment version will not save unfinished settings edits, and saving a setting will not create a new environment version.

For scripts that should run on each new devbox, open When a new devbox is created. For credentials each teammate needs to supply, open Environment and member files. You can configure these now or return to them later; see Maintain a Team Template for when later changes apply.

Let teammates use it

If you decided on Member projects, enable that mode now, after the first save: open the Member projects card and choose Set up managed projects…. The switch is permanent, so review the project types and requirements first. Otherwise each new project will get its own independent Template box.

Then create a test project yourself through New project... → Start from a Team Template. Check its tools, app startup, settings, integrations, and copied files. When the template is ready, send teammates Start from a Team Template.

Rename, archive, or restore a template

Open Template settings on the detail page to change the name or description.

Choose Archive when the team should stop using a template for new projects. Archiving will hide it from members and prevent new editing sessions while keeping saved versions and existing projects. To make it available again, open Archived in the Team Templates collection, select the template, and choose Restore in Template settings.