Set up a project with your local agent

If you already work with Codex or Claude Code on your laptop, that agent can run project setup for you from the terminal; the desktop app isn't required. 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. A second agent on the new cloud Template box will then install dependencies and get your app running.

Start locally

Open Codex or Claude Code in your project folder on your own computer and send:

Install the boxes.dev CLI with `npm install -g @boxes-dev/dvb`, then set up
this project on boxes.dev by running `dvb agent-init` and following its
instructions. Review the upload plan with me before launching setup.

The agent will guide you through dvb setup to sign in and connect a coding agent. That connection is what runs Codex or Claude Code on your cloud machines; the sign-in your local agent already has doesn't carry over. If you've already set up the CLI, start with dvb agent-init. Run this flow on your own computer, not inside a boxes.dev machine.

Copy the setup prompt into your local coding agent to begin preparing the environment. Select the image to enlarge it.

Review what will be copied

The agent will investigate your repositories, local configuration, databases, and app commands. It will write its choices in a commented YAML file called the setup manifest, stored outside your repository. Ask the agent for the manifest's path if you want to read or edit the file yourself.

Review these choices with the agent before approving launch:

• Which repositories, local edits, untracked files, configuration, and database contents to copy.
• Whether to import agent settings and any conversation history. No conversations are selected by default.
• Git access and any commands to run when new devboxes start.
• Devbox size, which will apply to the Template box and all of the project's devboxes and cannot be changed after creation.

Resolve any warning about an overlapping boxes.dev project or repositories skipped during discovery. Ask the agent to explain unfamiliar files or data before approving their upload.

Approve and follow setup

The agent will check the manifest and repository access before asking you to approve launch. Complete any GitHub connection or access request it shows. For SSH, add the supplied public key to the required Git hosts when prompted.

After approval, the agent will run dvb agent-init run to encrypt and upload the bundle, create your Template box, and start remote setup. If launch asks you to activate billing first, see Plans, seats, and box-hours.

When the remote setup thread starts, the local agent will offer to open the project in the desktop app. That's optional: dvb agents opens the same threads from your terminal (Use the CLI). Read the remote agent's progress and answer any questions. Provide missing secret values in Project settings → Environment files in the desktop app (Environment files and secrets), or open a terminal on the Template box with dvb connect from your own computer and edit the file there, rather than pasting them into the conversation.

When setup finishes, boxes.dev will validate the services and save the first snapshot. Check the agent's summary, then open your app — see Preview your app, or ask the remote agent for the run command and address — before starting your first task.

Resume or inspect setup

Ask your local agent to run dvb agent-init status after an interruption. It will report the current stage and the next action. Retry the action it shows. If you haven't changed the manifest, setup can resume the upload without sending completed parts again. If Git access has changed, restore access before retrying.

Advanced setup choices

The rest of this article is reference for reviewing the manifest in more depth. The agent runs these commands for you; you don't need them to complete setup.

Use dvb agent-init guide to read the workflow the agent follows. dvb agent-init start creates the manifest, and dvb agent-init check validates it before launch. Existing version-1 and version-2 manifests remain supported.

File selection and history

You can select individual repositories and shared files from a parent folder, with separate choices for tracked edits and untracked files. A long file list's preview may show only part of it; your include and exclude rules still apply to every file. Name Git-ignored files explicitly if you need them.

Environment and configuration files may be outside the project. Select an edited copy if you want different values uploaded while preserving your laptop original. Removing an explicit file entry will not exclude that file if a repository or untracked-file selection still includes it. Optional Bash and Zsh startup files will be adapted for Linux.

Conversation discovery starts with the selected repositories and their Git worktrees. The agent can run dvb agent-init detect agent-threads --all to find other conversations for you to review.

Git and database checks

Standard GitHub repositories default to automatic access; use dvb agent-init github connect when a connection is needed. Once GitHub is connected, the same command will open the GitHub page that gives boxes.dev access to your project's repositories. Automatic GitHub access and SSH for another host can be used together. One SSH key needs access to all repositories selected for SSH.

GitHub CLI access signs the gh command into your connected GitHub account on your boxes, for pull-request and issue workflows; it's a separate account-wide choice from Git pull/push access (Connect GitHub). Use dvb agent-init github cli status to inspect it, dvb agent-init github cli enable to turn it on, or dvb agent-init github cli disable to turn it off across projects.

For database copies, the manifest names the environment file and variable without storing the secret value. The check performs a dump without table data before requesting approval. PostgreSQL uses a compatible local client or the one packaged with boxes.dev; MySQL requires a local client. Fix any reported connection, authentication, or client-version problem before the full upload.

Startup, teardown, and maintenance

The manifest can include a startup script that runs while each new devbox is prepared, a teardown script that runs before a devbox is destroyed, and one Template maintenance script that keeps the base environment current: when files you watch in the project's GitHub repositories change, maintenance can run the script on the Template box and take a new snapshot. Review their paths and timeouts with the agent; Startup, teardown, and maintenance covers the full behavior.

Suggested startup commands will update new devboxes from your repositories' default branches; you can edit or omit them. Maintenance watches need GitHub App access even when pull/push uses SSH. Maintenance starts with its repeating schedule off and records the current repository state as its starting point; setup will save the configuration without running the script.