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 Member 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 Member 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 and choose your coding agents. The flow shows the exact saved version, the machine size, and a read-only summary of the project defaults you'll receive. The template sets the machine size, and it stays fixed for the project.
4. Supply the personal configuration the template requires, following the instructions your admins wrote: select each member file from your computer and enter the environment values marked required. Optional values can be entered now or added later. See Required member files and values.
5. Complete the Git access steps shown — the next section explains them — then choose Create project.

If creation fails, resolve the reported issue and choose Retry creation; returning to the same template reattaches to the unfinished creation. Cancel and clean up will 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. 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 shows your connected GitHub account's name and private no-reply email by default. Edit those fields only if you want a different identity; continuing with the displayed default will keep using GitHub. 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 in the project's Integrations sidebar. An independent project is usable in the meantime. In a Member 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. 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 devbox + 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 Member 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. If a required member file is missing, supply it under Project settings → Member files.

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.