Start from a Team Template

Use a Team Template to start with the repositories, tools, and dependencies your team has already prepared. In the desktop app, you'll create a project from the template, connect your own accounts, and supply any personal files or values your team requires, without needing a local checkout.

Which kind of project you'll create

A Team Template creates independent projects unless your admins have enabled managed projects on it. The project type determines how later template updates will reach you. If you're not sure which to expect, ask a team admin.

• An independent project gives you your own Template box — a personal copy of the team's saved environment — with its own snapshots. You can change that environment yourself, and later saved Team Template versions won't change it. If the template includes a maintenance script and schedule, your project will receive its own copy, which can update your Template box on that schedule; manage it under Startup, teardown, and maintenance.
• A Managed project has no personal Template box. Each new devbox will start from the team's current saved environment, so when an admin saves an update, your future devboxes will use it; existing devboxes will keep their files. Ask a team admin when the shared environment itself needs a change.

In both kinds, the project and its devboxes are yours, and work you do in a devbox will not update the Team Template. Leaving the team won't remove an independent project.

Create your project

1. Open New project... in the desktop project selector and choose Start from a Team Template.
2. Select your team's template. Only templates with a saved version appear; if you don't see a suitable one, ask a team admin which to use.
3. Name your project. For an independent project, choose your coding agents too. Select at least one if the template includes setup instructions. You can review the team defaults in the form; the template sets the machine size, and it stays fixed for the project.
4. Complete Needed to create the project: enter the required environment values and select the required files from your computer, following your team's instructions. Choose Show optional to add anything else your tools need now, or add it later in Project settings. See Required member files and values.
5. Complete the Git access steps shown — the next section explains them — then choose Create project.

The actions stay at the bottom of the form. If anything is missing, select its name there to jump to it. Choosing Create project also marks missing fields and moves you to the first one.

Change template returns to the picker and keeps your entries. Choose Back to setup to return to them. If you've entered anything, choosing a different template or closing setup will ask before discarding it. Entries are kept only while setup stays open; reloading the app clears them.

If an error leaves you on the form, resolve it and choose Create project again; your entries will still be there. If creation has already started, returning to the same template will reopen the unfinished attempt. Use Retry creation when offered, or Cancel and clean up to remove the incomplete attempt and its allocated resources.

Choose From Team Template to start with an environment your team has prepared. Select the image to enlarge it.

Complete Git access

Your project pulls and pushes with your own Git access, not an admin's. For the template's GitHub repositories, creation checks your GitHub connection and pull/push access, and shows the exact connect, authorization, install, or grant-access step to complete. If your GitHub account can only read a repository, or can't reach one that boxes.dev already can, ask an owner of the repository's GitHub organization or account to give you write access. Setup offers a request message you can copy and send. For an independent project, access is also checked for any repository the template watches for maintenance — a watch names repository paths whose changes will trigger a maintenance run — even when the watch is disabled.

An independent project can also contain repositories on other hosts. For SSH remotes and GitLab HTTPS remotes, the flow will show a new public SSH key created inside your project's Template box, with instructions for the detected hosts. Follow them: add the key to each listed host, then choose Verify access. For other remote formats, finish the host's authentication in Terminal or with the setup agent. A project with no GitHub repositories needs a GitHub connection only when something else in the project uses one, such as a maintenance watch on a GitHub repository.

For commit authorship, setup summarizes your account Git identity. By default, this comes from your connected GitHub account's name and private no-reply email. Edit account identity opens the name and email fields; changes will update your account identity when you create the project. If Git identity is off for your account, setup keeps it off unless you choose Turn on for your account. You can change it later in Account → Git identity. See commit identity and signing for how imported or repository-specific Git settings take precedence.

Finish integrations and optional setup

If the template requires integrations such as Slack, Linear, AWS, or Tailscale, you'll connect them after the project is created. Connect each integration marked Required; you can't finish this stage until those connections are ready. Because finishing closes this initial setup permanently, decide about the Recommended integrations here too: connect them, or choose Finish without recommendations to leave them out. If an integration disconnects later, you'll see the ordinary integration warning, but setup will not reopen. If a shared team connection is broken, ask a team admin to repair it.

You can leave this stage and return to it later through Finish setup beside Integrations in the sidebar or on the Integrations page. An independent project is usable in the meantime. In a managed project, boxes.dev will not prepare your first devbox until you finish this stage, so finish it before you plan to start working.

The project may also inherit MCP connections: tool connections whose settings the template provides without anyone's credentials. Sign in or add your own key for each one, and choose which agents can use it. In managed projects, team definitions stay current and cannot be edited or deleted by members. Matching personal connections are adopted with their existing credentials; other personal MCPs stay available. Connecting either agent is optional. See Team Template MCPs.

In an independent project, if you already have an account-wide connection — one that applies across all your projects — with exactly the same settings, boxes.dev reuses it. If an account-wide connection has the same name but different settings, your account-wide one keeps applying; rename the inherited connection to keep both, or skip it.

For an independent project, the template may include setup instructions. Once the project is usable and any required integrations are finished, boxes.dev will start a setup agent thread from those instructions. Open that thread to answer the agent's questions and read what remains for you to do; the agent will validate the environment and take a new snapshot when it finishes. If the setup thread or an inherited resource such as a Project URL fails, the project remains usable — retry from the Template setup needs attention row in the project's sidebar.

Start working

Once the required integrations, values, and files are in place, choose New thread and ask the agent how to run the app. With that thread selected, the ports control in the titlebar lists the ports detected on its devbox; open your app from there and check that your own credentials and required files work. See Preview your app. From here, request changes in the same thread; for a guided first change, see your first task.

If a devbox can't start

In a managed project, a notice beside your unsent message will explain what's missing — an agent connection, GitHub repository access, or an unavailable template — with the action to fix it. A member file that can't be written to its destination will also stop the devbox, and Project settings → Member files will explain what to change.

A missing required environment value or member file won't stop a devbox. It will start without it, and the workbench will show a warning with Open Project settings so you can add it.

If the team's environment fails to prepare, choose View details and use Copy details to send the error to a team admin. Your unsent message and attachments will remain available while the admin fixes the problem; send your message again afterward.

A startup script failure is different: the devbox and agent will still start. The team's script runs before your project's startup script, after your connections and files are ready. Open or copy a warning's details, then ask a team admin to correct a team script or edit your own script in Project settings. A correction will apply to future devboxes; run any needed repair on the current machine yourself or with the agent.