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. Run these commands yourself and ask for my
approval when needed.

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.

If your agent runs somewhere else, such as Codex cloud, it will tell you before continuing. Setup will copy your project from that environment, so the environment needs to run your app with its configuration and services. Files and agent settings on your own computer won't be included.

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. To use OpenRouter, Vercel AI Gateway or your own endpoint with Codex, add a connection under Codex model providers on the same page. You can continue with that connection without signing in to OpenAI.

After you sign in, the same tab will return to Connect your accounts. You don't need either agent installed on your computer. These connections run Codex or Claude Code on your devboxes; 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, such as one you reach over SSH or a cloud environment like Codex cloud, 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.
• Which starting branch to use for both Template setup and new devboxes. The agent will recommend the repository's default branch, often main or master.
• Whether to import agent settings and any conversation history. No conversations are selected by default. Your Claude permission rules will be left out unless you ask for them; included rules will be saved in your project's Agent settings.
• 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.

Ask the agent to recommend the smallest devbox that fits one coding agent, one running instance of your app, and its required services. A marketing site or modest app is a candidate for 4 vCPU / 8 GB; ask what needs more resources before choosing a larger size. Review the box-hour multiplier too: a larger size will consume your included usage and prepaid credits faster while awake, even when the extra capacity is idle. Each devbox has its own resources, so you do not need to fit every planned devbox's work onto one box.

Review the estimated upload size and its largest categories. Your agent can select individual Claude and Codex skills; their sizes include linked tools and supporting files. Ask the agent to recommend skills and configuration that will help with this project and your development workflow, and to explain the value and size of large imports. Testing or browser skills may be useful even when your app does not require them. Review large or uncertain choices before approving launch. Keep the configuration and assets you want; excluding something from the upload will not delete the local original.

If your checkout differs from the selected branch, the agent will ask which unfinished work to save on boxes.dev as part of that file review. For example, if you choose main while working on feature-123, the remote agent will save included work on its original branch with a named Git stash, then run setup on main. Edits already on main will also be saved separately. Your local checkout will stay intact, and approved configuration needed for setup will remain available. The setup summary will explain how to resume saved work in a devbox; new devboxes will start on your selected branch. The saved work will be included in the Template snapshot; it won't be pushed to your Git remote.

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, or your chosen Codex model provider. Usage will count against that account's allowance or the provider's 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.

For a Codex model provider such as OpenRouter or Vercel AI Gateway, ask your agent to choose the connection and one of its models explicitly. Setup will use that choice and the model's default reasoning level. If the connection or model is unavailable, resolve the error before continuing; setup won't switch to another provider. An OpenAI account isn't required for this path.

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, when the plan still has unfinished parts, and when the setup plan is ready for your review. If a check finds no connected account or Codex model provider for the coding agents in the plan, the page will ask you to add one. Ask your agent to run dvb agent-init accounts, then add an account or provider on the page it links to and click Done. If you've already connected a different coding agent, ask your agent to use that one in the plan instead. 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. When setup can't continue until you check your coding agent, such as when the plan is ready for your approval, the current stage will stop spinning and show what it's waiting for. 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 Preparing or Waiting for your approval. 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 or Linux computer, 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. If you haven't used the desktop app before, sign in with the same boxes.dev account. It won't ask you to connect your coding agents again, and it will show its accounts screen only if GitHub isn't connected yet. On other operating systems, or when your agent runs on another computer, 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 or Linux computer, 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.

To restart an incomplete setup with a smaller import or devbox size, ask the local agent to stop its upload and run dvb agent-init destroy --yes after you approve the reset. This will remove the incomplete Template box and setup progress while keeping the agent's manifest and your project files. The agent can reuse your earlier choices, revise the manifest, and show the new import size and usage cost before asking you to approve launch again. If setup has already completed, keep the project until you decide whether to recreate it; its devbox size cannot be changed in place.

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.

Setup model provider

After saving a Codex model provider connection in boxes.dev, run dvb threads options --json to find its connection ID and models. Include codex in agents.runtime, and set these fields in the manifest:

agents:
  runtime: [codex]
  setup:
    backend: codex
    model: <model-id-from-options>
    codexProviderConnectionId: <connection-id-from-options>

Keep your API key in boxes.dev; the manifest needs only the connection ID. Omitting codexProviderConnectionId, or setting it to null, keeps the ordinary OpenAI or Claude account selection. If you have only a model provider connected, choose it explicitly before launch.

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. Repository uploads include Git history and local branches, including commits you haven't pushed. Excluding local edits or untracked files won't exclude those commits. Git worktrees inside a repository are left out by default, but their branches will still be uploaded.

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. You can also import conversations after setup.

dvb agent-init detect agent-config lists skill names, selection ids, and sizes; --json also includes their source paths and exact byte counts. The manifest's agentConfig.include can select individual skills by those ids. Existing claude:skills and codex:skills entries mean the whole folder. Remove an agent's whole-folder entry before selecting a subset of its skills. The local originals and the files a selected skill needs will stay intact.

Git and database checks

Standard GitHub repositories default to automatic access. When the boxes.dev GitHub App can't access a repository yet, your agent will explain your options, then open GitHub while it keeps preparing your setup. You can give the boxes.dev GitHub App access to the listed repositories, which an organization owner may need to approve, or tell your agent to use an SSH key on your GitHub account instead. SSH covers pull and push; automatic pull request updates and follow-ups still need App access. Your agent will run dvb agent-init github connect, which will connect GitHub if needed and then open the GitHub page that gives boxes.dev access to your project's repositories. The command will keep checking while you finish on GitHub, so your agent will continue once boxes.dev has access without you telling it you're done. The page where you copied the prompt will show each step: Connect GitHub while you sign in, then the repositories to give access to and an Open GitHub link. The command will stop after 20 minutes without progress; if an organization owner's approval takes longer, ask your agent to run it again. If your agent's setup check finds that GitHub isn't connected or needs to be reconnected, the page will show a Connect GitHub or Reconnect GitHub button; after you sign in, ask your agent to check again. 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.

The manifest's generated Git commands tell boxes.dev which branches to use for new devboxes. When all selected repositories have a known remote default branch, the agent starts with defaults for each one, including repositories in subfolders. Keep those paths aligned with the repositories you choose to import. boxes.dev saves those defaults separately and prepares the branches before running any extra startup commands. Ask the agent to review the branch choices with you. Commands after the generated block will run on every new devbox, so keep them quick, such as a locked dependency install; one-time setup happens on the Template box. Normally choose a starting branch, usually main, so new devboxes fetch fresh code from the remote repository. If your chosen branch exists only locally, the agent will ask whether to use its clean committed state from the Template snapshot instead. For that choice, omit the generated block; unfinished work will still be saved separately. If no default is saved, or it doesn't match a remote starting branch, the setup agent on the Template box will save that branch before setup finishes, unless your own startup commands switch branches themselves. After setup, clearing the startup script will keep saved branch defaults.

The agent should recommend maintenance and keep it small, usually updating your starting branch and installing locked dependencies, so the Template box doesn't fall behind. It should watch files such as lockfiles rather than all of your source code. Maintenance watches need GitHub App access even when pull/push uses SSH. Maintenance will start with its repeating schedule off and record the current repository state as its starting point. The setup agent on the Template box will test the script twice and save any fixes it makes; setup won't start a maintenance run.