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 desktop app offers this path first when you create a project, and its 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 the desktop app's Set up with your coding agent card, or start from your terminal without the desktop app.

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 when you don't have the code on your computer, you're starting from 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. 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 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. The GitHub step signs you in; boxes.dev will ask for repository access later, once it knows which repositories your project uses.

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: in the desktop app for the coding-agent, Team Template, and local-folder paths, or on the boxes.dev website for GitHub setup. 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, its setup chooser shows an availability message instead of the Mac download and app-opening controls.

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.

Open your project after setup

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.