Set up from a local folder

Local-folder setup copies your codebase and working development environment from your laptop to the project's Template box, where you'll prepare the environment for future devboxes. In the desktop app, setup agents will inspect your laptop, and you'll review the files and data selected for upload before boxes.dev copies them to the cloud.

Select your project

Signing in to the desktop app for the first time opens setup. To add a project after your first, choose New project... in the desktop project selector.

1. Open the desktop app and sign in. Connect Codex or Claude Code when prompted; you can use your existing agent account or an API key.
2. On the Project step, open Other setup options at the bottom of the setup choices, then choose Browse... and select your project folder on your laptop. For several related repositories, choose their parent folder, then select the repositories to include; you can't change which repositories are included after setup begins without starting over. If setup warns that the folder overlaps another boxes.dev project, continue only if you intend to create a second project from those files.
3. Enter a project name using lowercase letters, numbers, and dashes.
4. Choose a devbox size under Instance type. This size will apply to the Template box and all of this project's devboxes, and cannot be changed after creation.

Review the setup scans

Before the scans run, choose their scope: Project + local config looks outside the repository for requirements such as environment files and local databases, while Project only limits scanning to the selected project folder. You can skip scans you don't need.

The setup agents will then look through your laptop for environment and secret files, required tools, extra files, local databases, and the commands that run your app. These scans are read-only: finding a file does not approve its upload.

Review each group's findings, select what to include, and approve each required section; setup can't continue until they're approved. If something is missing or wrong, tell the scan agent what to change and rescan. Add a setup note for any instructions the remote agent will need.

Approve database copies only if the data belongs in your cloud development environment. Setup will check each connection before copying its contents.

Review the detected files, configuration, and app commands before approving the setup plan. Select the image to enlarge it.

Check the final bundle

In Finalize Bundle, review the files and settings that will be sent:

• Repository contents and Git history, with separate choices for your local edits and untracked files.
• Approved configuration, extra files, database copies, and setup instructions.
• Optional Codex and Claude settings and conversation history.
• Git access and the optional Devbox startup script.

This review is your last chance to adjust what gets copied; Fine-tune what gets copied covers untracked files, environment-file edits, agent history, and databases in detail.

For GitHub repositories, complete the connection or repository-access request shown under Git access. Automatic GitHub access is selected by default: your Template box and devboxes will pull and push as your connected GitHub account, with no SSH key to register. You can explicitly choose SSH instead, and other Git hosts use SSH. You can also skip Git access and configure it later, though devbox work usually needs working pull and push. To change the bundle's Git-access choice after upload, you'll need to restart setup. For GitHub CLI access and commit signing, see GitHub connection and access.

The startup script will run when each new devbox is created, before its first agent prompt. The suggested commands will refresh the devbox's checkout from your repositories' default branches. Edit them for your workflow or leave the field blank.

Upload and finish setup

Approve the bundle to upload it. boxes.dev will encrypt the upload, create the Template box, and start a setup agent there. The agent will install missing tools, place the approved files, import databases, and run your app's setup commands. It will preserve tracked source, tests, manifests, and lockfiles unless you've authorized changes in your setup note.

Open the setup thread to read progress or answer questions. Provide missing secrets in Project settings → Environment files (Environment files and secrets), or through Files or Terminal with the Template box selected, rather than pasting values into the conversation.

When the setup agent finishes and hands the work back, boxes.dev will validate the configured services and save the first Template box snapshot for new devboxes. Read the setup summary for the build or tests that passed, services that started, and anything skipped or still needed. Ask the agent to check tool versions and a normal project command from a new terminal session, so the setup doesn't depend on temporary shell changes.

With the Template box selected, open your app from the ports menu in the titlebar and try an important workflow. If it doesn't work, ask the setup agent to continue, then take a new snapshot once the app works so new devboxes get the fix. Otherwise, you're ready for your first task.

Fine-tune what gets copied

Everything in this section happens during the scan review and Finalize Bundle stages, before upload.

Repositories and local files

For several repositories, use Git repositories to include their history and Other project files for shared files. Repositories selected as ordinary files will be copied without Git history.

Dependency, build, cache, and disposable agent-worktree folders are excluded by default. Use Customize in the untracked-file review to include or exclude individual files and folders. Select Git-ignored files explicitly when you need them.

For a shallow repository (a clone with limited history), older commits won't be included. To include them, open Get full history, run the displayed Git command locally, then choose Refresh repository. Setup will not fetch older commits itself.

Environment files and shell settings

Edits in the environment-file review change a private copy, leaving the original on your laptop untouched. Use Reset from original to copy the current file again, or Add env file… for a file the scan missed. Files already tracked in Git are included with the repository.

Optional Bash and Zsh startup files will be adapted for Linux. Setup also imports portable Git settings and reports anything that needs configuration.

Agent history, configuration, and plugins

Conversation history is off by default. Use the picker to choose project conversations or show other history. Importing conversations copies history only. To continue an imported Codex or Claude conversation, connect that agent in boxes.dev.

Supported agent settings, skills, and MCP definitions can be copied. Local MCP servers are unchecked by default because they depend on your laptop; remote MCP connections may need you to sign in again. Plugin bundles and their configuration are not imported. Install them afterward through agent plugins.

Database tools

For a failed database check or copy, start the database or fix the reported connection or client problem, then retry. PostgreSQL copies can use the client included with boxes.dev; MySQL and MariaDB require a compatible local mysqldump. You can skip a failed database without removing successful copies.

Resume an interrupted setup

If your folder already belongs to a project, open that project or resume its setup.

Open Setups in progress in the desktop project selector and choose Continue setup. Completed reviews are retained. Use Retry scan for a stopped scan or Retry upload for a failed upload.

If you pressed Stop during remote setup, choose Open setup thread and continue that conversation. It will stay paused until you do. For a remote Git-access failure, Fix Git access will remove the incomplete Template box and return you to the final review with your approved choices preserved.

Each entry under Setups in progress also has a delete control. Deleting removes only the incomplete setup state; the original folder on your laptop won't be affected. Follow the displayed action for billing or project-limit blocks. If recovery keeps failing, send the error and request ID to support.