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 Team Template member 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 devbox + 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 out of the active thread list while keeping it readable, and the devbox stays available. 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 any reported uncommitted changes and local-only commits. Destroying the devbox will permanently delete the local files on the machine; files in shared project storage will remain.
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.

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 appear under Archived chats in the sidebar, and you can read them without a running machine. 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 ordinary project's Template box. Restoring will not recover the destroyed devbox's files or unpushed commits.

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.