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

Copy the setup prompt from Get started on the boxes.dev website, which you'll see after signing in for the first time. For a later project, copy it from New project on the website or from the desktop app's Set up with your coding agent card. Then open Codex or Claude Code in your project folder on your own computer and paste the prompt. It looks like this:

Install the boxes.dev CLI with `npm i -g @boxes-dev/cli`, then set up this
project on boxes.dev by running `dvb agent-init --login-code <code>` and
following its instructions.

The login code signs your agent in to your boxes.dev account, so you won't need to sign in again. Each code works once and expires within 30 minutes, and the textbox automatically generates a new code after use or before it expires. If a code you already copied no longer works, the agent will have you sign in to boxes.dev in your browser instead, or ask for a fresh prompt if it runs on another computer. 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.

Connect your accounts

Next, the agent will open Connect your accounts in your browser. Choose Connect beside Codex or Claude Code and finish signing in, or choose Use an API key. After you sign in, the same tab will return to Connect your accounts. You don't need either agent installed on your computer. This connection is what runs Codex or Claude Code on your cloud machines; the sign-in your local agent already has doesn't carry over. You can also connect GitHub and Slack here, though both are optional. Choose Done when you're finished, and the agent will continue.

If Codex or Claude Code already shows as connected to boxes.dev, you don't need to sign in again. Still choose Done to continue setup with that account; leaving the page without choosing Done will leave your agent waiting.

If your agent runs on another computer that you reach over SSH, it will give you a link to open instead. On that page, Codex will show a one-time code to enter on ChatGPT, and Claude Code will ask you to paste the code Claude shows. Choose Done, then tell the agent you're done.

If the browser can't return to your agent, choose Use a code instead on the accounts page. After signing in with a code, choose Done to finish the waiting setup step. If an older CLI keeps waiting, tell your agent you clicked Done so it can check setup status and continue.

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.

The agent will set up the repository you opened it in. If it finds that you develop several repositories together, for example because one depends on another, it will suggest including them and ask you first. If you open it in a folder of unrelated repositories, it will ask which one to set up.

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.

Remote setup will run as a regular thread using your connected Codex or Claude Code account and its usage allowance or API credits. Your local agent can record its current model in the manifest. Remote setup will prefer that agent when selected and connected, and use that model when available. If the model is unavailable, setup will use the chosen agent's account default. Without an agent preference, setup will prefer Codex when both agents are selected and connected. Setup will request high reasoning where supported. You can continue that thread after setup finishes.

While your agent works, the page where you copied the prompt will show how setup is going: when your agent connects and prepares the project, when you need to connect your accounts or GitHub or add an SSH key, and when the setup plan is ready for your review. If a setup command fails, the page will show its error. Once your agent connects, the prompt will move behind Setup prompt; open it if you need to copy the prompt again. On Get started, you can reload the page and keep following along. Once the upload starts, the page will show its percentage.

In the desktop app, each project your agent is setting up has its own setup page, which shows the same progress and lists the remaining setup stages. If you copied the prompt from the desktop app, the page will open when your agent starts working on the project. You can also find the setup under Setups in progress in the project selector, where it shows its current status, such as Plan ready for review or Waiting for you. Choose it to open the setup page.

When the remote agent starts working on the Template box, your local agent will tell you where to follow along. On a Mac, it will offer to open the desktop app on the setup thread, or give you a link to download the app if you don't have it yet. On other computers, it will point you to the mobile app. The desktop app is 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. If the desktop app is installed on your Mac, your local agent will open it on the setup thread. Check the remote 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

If the remote agent has replied or you've stopped it without completing setup, open its thread in the desktop app. Continue the conversation if more work is needed, or choose Mark setup completed in the banner when the environment is ready. boxes.dev will validate it and save the first snapshot before marking setup complete.

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.

If setup stops before the remote agent starts, the project's setup page in the desktop app will show what went wrong and the retry command to give your agent. To abandon the setup after the upload starts but before the remote agent starts, choose Delete setup on the setup page. This will delete the Template box, if setup created one, and the setup progress saved on your computer, including the setup manifest. Files in your project folder won't be affected.

If your agent hasn't reported on a setup for over a day, its setup page will say that setup is waiting for your coding agent. Ask the agent to run dvb agent-init status and follow its next step. The page will update when the agent runs its next setup command.

If you no longer want the agent's setup, choose its project folder in the desktop app, then choose Delete setup on the setup page that opens. This will delete the setup progress saved on your computer. Your agent's setup manifest and the files in your project folder won't be affected.

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. If a repository was renamed or moved on GitHub after you cloned it, dvb agent-init check and github connect will show a git remote set-url command that points your local copy at the current name. 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.