Create and manage devboxes

Use a devbox for a feature, bug fix, or experiment that needs its own machine in the cloud. Each devbox keeps its own local files and runs its own programs, so work on those files and programs stays on that machine. Devboxes can still affect one another through an external database or service they use, or files you deliberately keep in shared project storage.

Create a devbox

A new devbox starts from your project's latest saved Template box snapshot. If newer changes on the Template box should come along, take a snapshot first; if no snapshot exists yet, the creation flow may offer to take the first one. A managed project has no Template box of its own — its new devboxes use the Team Template's current saved version instead.

1. In the desktop sidebar, choose New thread (Cmd+N, or Ctrl+N on Windows and Linux).
2. Select Codex or Claude, then write and send your request.

Once you select the new thread, Terminal, Files, Git/Review, Browser, and Ports will all use its devbox. The devbox starts its own processes; it will not resume programs that were running on the Template box.

If your project has a startup script, boxes.dev may run it while you're still typing, before you send the request, so read Startup, teardown, and maintenance before configuring a script with effects outside the devbox. A failed startup script can leave the devbox usable with a warning in the thread; check that warning before relying on your app.

An agent running on your laptop can also create a devbox without starting a conversation. See Agent command reference.

A new devbox starts from the saved environment shown above the task composer. Select the image to enlarge it.

Start another conversation on the same files

When another conversation should use the files already on a devbox, open the devbox row's … menu in the sidebar and choose New thread. Both agents will share the machine's files and running services, so give them work that won't edit the same files at once.

Archiving an additional thread moves its conversation to an Archived threads list inside the devbox's group, where you can still read it, and the devbox stays available. If you archive the devbox's first thread, the devbox will stay in the list, but you'll need to unarchive that thread before starting another one there. Use the devbox row itself for actions that affect the whole machine.

Move work off the Template box

If a Template box conversation turns into feature work, you can move it to its own devbox. Wait for the agent to finish its current turn first. The new devbox will start from the latest saved Template box snapshot, so take a new snapshot if the conversation depends on current Template box files.

Open the thread's … menu and choose Move to new devbox, when available. The conversation will move to the new machine. If the move fails and Move back to Template box appears, use it to return the conversation to its original machine.

To keep the original chat and start a separate conversation from a particular response instead, use Continue in new chat; that action can copy the source machine's current files.

Finish and clean up

Review and test the changes, then commit and push your code, or download files you want to keep. Code on a devbox isn't pushed to your Git remote or added to a Template box snapshot automatically. Devboxes created by automations and integrations work the same way: review the thread, save what's useful, then sleep or destroy the machine.

Sleep the devbox if you expect to return to it. When you're finished with it:

1. Open its row's … menu and choose Destroy and archive. A devbox with several threads offers Destroy and archive all.
2. Read the confirmation, including whether an agent is still working and any reported uncommitted changes and local-only commits. Destroying the devbox will stop that agent and permanently delete the local files on the machine; files in shared project storage will remain. If the devbox's agents handle automatic PR follow-ups, the confirmation lists those pull requests, and their follow-ups will stop.
3. Confirm only after saving everything you need elsewhere.

boxes.dev will stop active Codex or Claude work and preserve the devbox's conversations, including threads you had already archived. If the history can't be archived safely, boxes.dev will keep the machine and report the failure.

For a forked Codex conversation with missing parent history, boxes.dev will first try to recover it from your saved thread archives in the same project. If the required history is still missing, the app will list the affected threads. Choose Keep devbox, or review Destroy anyway: those threads will remain readable as History only, but you will not be able to continue them. Healthy threads will remain restorable. If readable history has not finished syncing, the devbox will stay available; retry after syncing or delete the affected thread before destroying the devbox. Automatic cleanup will not make this choice for you.

Destruction is also blocked while another thread on the devbox has a draft with unsent text. Open that draft and discard it — copy the text somewhere else first if you want to keep it — then try again.

The preserved conversations will appear in the sidebar under Devboxes → Archived threads, grouped under the devbox's name, and you can read them without a running machine. On mobile, they'll appear in Archived threads at the end of the project. Open one and choose Restore thread from its actions to continue it on a new devbox created from your project's saved starting point, or on an independent project's Template box. Restoring will not recover the destroyed devbox's files or unpushed commits.

If a fork cannot restore because the Template box has an incomplete or different copy of its parent history, choose Restore to new devbox when offered in the thread's warning. The parent on its current box will be preserved. Otherwise, restore the original thread on the Template box before retrying. You can also leave the thread archived and restore it later.

Use the devbox thread menu to sleep the machine or destroy it and archive the thread. Select the image to enlarge it.

When capacity is full

Your plan limits how many devboxes can be awake at once. At the limit, boxes.dev will ask you to sleep another devbox before it can create a devbox, wake one, move work to one, send a message to a thread on a sleeping one, or run an automation now.

The chooser shows which devboxes are idle, which have open terminal activity, and which have an agent working. Pick one whose work can pause: nothing on that machine will run while it sleeps, and sleeping a devbox with active work may interrupt that work.