Choose how to set up your project

If your codebase and development environment are already set up on your laptop, hand setup to the Codex or Claude Code you already run in your terminal: the agent will do most of the work, and you'll review everything before any upload happens. The website and the desktop app offer this path first when you create a project, and the desktop app's local-folder setup reaches the same result through a guided wizard.

Each project can contain one repository or several related ones. The coding-agent, local-folder, and GitHub paths all create an ordinary project with a Template box, the base machine in the cloud used to prepare the starting environment for new devboxes (How boxes.dev works has the full picture).

Choose how to bring your code and development environment into boxes.dev. Select the image to enlarge it.

Choose your starting point

With your local coding agent

Local-agent setup hands the work to the Codex or Claude Code you already run in your terminal. The agent will inspect your codebase and local configuration, write an upload plan for you to review, and hand the approved work to boxes.dev. Copy the prompt from Get started or New project on the website, or from the desktop app's Set up with your coding agent card.

From your team's environment

Use a Team Template if your team has already prepared the code, tools, and services. You'll start from that saved environment, with any personal files or values the template asks you to supply.

From a local folder

Use local-folder setup to copy a working development environment from your laptop, reviewing the upload in the desktop app's setup wizard instead of with your terminal agent. Either path can find dependencies outside the repository, such as environment files and local databases, that a GitHub clone would miss. In the desktop app, this option is under Other setup options at the bottom of the setup choices.

From GitHub

Use GitHub setup for a later project when you don't have the code on your computer, you're on your phone, or you're starting a brand-new repository. boxes.dev will clone your selected repositories and configure Git access. Cloning brings committed code only, so you'll then provide any secrets, ask an agent to install dependencies and get your app running, and take a snapshot so devboxes inherit the finished environment.

GitHub setup is available once you've set up your first project. When you add another project in the desktop app, this option is under Other setup options, below the local folder, and is marked Manual setup. On the website, it's on the New project page. On a phone, create the project in your browser on the boxes.dev website, then continue in the mobile app.

Before you begin

Sign in to boxes.dev and connect at least one coding agent. Use your existing ChatGPT login for Codex, your Claude login for Claude Code, or an API key for either agent. You can connect both. See Connect Codex and Claude.

The desktop app's first setup page, Connect your accounts, also lets you connect GitHub and Slack before you choose a project. Both are optional. With your local coding agent, the agent will open a Connect your accounts page in your browser, where you can connect your coding agents, GitHub, and Slack. The GitHub step signs you in; boxes.dev will ask for repository access later, once it knows which repositories your project uses.

After connecting GitHub, you can choose optional personal GitHub CLI access to let agents use your repository permissions, including starting workflows. The GitHub App connection covers pull, push, pull requests, and limited CLI commands. Choose Enable under Full GitHub CLI access (optional) during setup for broader CLI use, or skip it and connect later in Account, Integrations, or with gh auth login.

Make sure you can grant the Git access requested during setup. For repositories in a GitHub organization, an owner may need to approve access. If you're copying local files or databases, review the selected contents before approving the upload.

During setup you'll also choose a devbox size. It will apply to the Template box and all devboxes in that project, and you cannot change it after creation. Every size includes a 100 GB disk, and the picker shows each size's CPU, memory, and any box-hour usage multiplier.

Where setup starts

Signing in for the first time opens setup on its own. On the boxes.dev website, you'll see Get started, where you can connect GitHub and copy the setup prompt for your coding agent. In the desktop app, the setup wizard offers the coding-agent, Team Template, and local-folder paths. To add another project later, open the desktop project selector and choose New project..., or choose New project on the website's Projects page. The coding-agent path can also start from your own terminal without the desktop app.

The desktop app is available for macOS. When the website identifies Windows or Linux, Get started points you to the mobile app instead of the Mac download.

Resume an interrupted setup

Look under Setups in progress, in the desktop project selector or on the website's Projects page, and choose Continue setup. In the desktop app, a setup your local coding agent started will show its status instead; choose it to see its progress, and ask the agent to run dvb agent-init status to continue.

Open your project after setup

After local-agent or local-folder setup, read the setup thread's final reply for what the agent checked, anything still to do, and a short introduction to using boxes.dev. It will explain how to start an isolated task with New devbox + thread, add a thread to an existing devbox, and get started with Slack, Linear, automations, and agents working together. Keep talking in that thread if you need help. If setup is still finishing, wait for the first snapshot to finish before starting a devbox.

On the website's Projects page, choose your project name or Open in desktop app to continue in the app. On a phone, choose Open in mobile app.