Install and use the CLI

The dvb CLI lets you work on your cloud devboxes from a terminal on your computer. You can continue the same Codex and Claude threads you use in the desktop app, or open a shell to run commands yourself.

Do not install or run the workstation dvb CLI inside a boxes.dev machine. Doing so can destabilize or permanently break the machine; boxes.dev is not responsible for recovering a machine knowingly modified this way. Agents already on a devbox use the separate dvb-onbox commands.

Install and sign in

If you have Node.js 22 or newer, install the CLI with npm in a terminal on your computer:

npm install -g @boxes-dev/dvb

On macOS or Linux with an x64 or arm64 processor, you can instead install the standalone build, which includes its own runtime:

curl -fsSL https://boxes.dev/install.sh | sh

After either installation, run dvb setup to sign in and configure agents. CLI sign-in is separate from desktop sign-in. Use dvb setup --agents to repair only agent authentication.

If you haven't created a project, follow Set up a project with your local agent. For command options, run dvb --help or dvb <command> --help.

After setup, use dvb agents to find a saved thread or start a task. You can also start a task directly in the agent's terminal with dvb codex or dvb claude, or open an ordinary shell for your own commands with dvb connect. For scripts and coding agents that need explicit targets and JSON output, see Agent command reference.

Continue an agent conversation

Run dvb agents to open a list of your threads. If you have several projects, choose one when prompted, or supply it with dvb agents <project>. Select a thread and press Enter to continue the conversation on its existing machine. Codex can remain open on desktop at the same time. Claude accepts input from one place at a time and will ask before transferring control.

The thread list is called the switchboard. Its main shortcuts are:

The CLI switchboard lists your threads and lets you open or create a conversation. Select the image to enlarge it.

Start a thread from the switchboard

1. Press n to use the selected machine or N for a new devbox.
2. Check the target shown around the composer. Use Tab and arrow keys to choose agent settings, or type / first for commands such as /model and /reasoning.
3. Write your request.
4. Press Enter to start work in the background, or Ctrl+O to start work and open the agent terminal when it's ready.

Esc will keep a nonempty unsent draft and discard a blank one. After Ctrl+O starts work, Esc will cancel only the automatic opening of the terminal; the agent will keep working.

Agent choices sync with desktop and mobile; model, reasoning, and speed defaults follow the selected machine.

A pencil (✎) marks an unsent draft. Press Enter on that row to edit it again. If a first send fails, open Retry failed start to review the saved request and try again.

Return to the list without stopping work

In Codex, Ctrl+D from an empty composer returns to the switchboard without interrupting work; Esc interrupts the current response. In Claude, Ctrl+\ returns to the switchboard without ending its persistent terminal. An idle Claude terminal allows normal machine sleep; press an ordinary key to wake and reconnect — that key wakes the machine instead of typing into Claude — or press the displayed detach key to leave without waking it.

If your connection drops while Claude's machine is still running, the CLI will reconnect to the same terminal automatically. Transferring control from another terminal, desktop, or mobile still requires confirmation.

Keep the list beside your agent

Use dvb agents --workspace for a split view of the list and the selected agent or shell. Select a row, then press Enter for its agent or t for its shell; moving through rows alone won't change the open terminal. Narrow windows show the focused pane, and resizing will adjust the layout without restarting your agent. This view requires tmux 3.3 or newer on your computer and cannot be combined with --json.

dvb agents --bell rings when a thread newly needs input. --json provides a bounded inventory instead of the interactive switchboard and cannot be combined with --bell. For archives and additional pages, use dvb threads list.

Start or resume a native interface

To start a new thread with an empty Codex or Claude terminal, run one of these commands and type your first message there:

dvb codex [project] [--devbox <devbox>]
dvb claude [project] [--devbox <devbox>]

Brackets mark optional arguments; omit the brackets when typing them. Without --devbox, the new thread will get a new devbox from the latest Template box snapshot or saved Team Template version; if your personal Template box has no snapshot, take one first. With --devbox, the thread starts on that existing machine; find machine names with dvb list.

To reopen an existing thread, pass the agent's native ID with --resume instead of --devbox:

dvb codex [project] --resume <native-thread-id>
dvb claude [project] --resume <native-session-id>

With --resume, the command will reopen that thread on its recorded machine without creating a thread or devbox. To get the ID, open the thread's action menu in the desktop app and choose Copy session ID (see Organize and share threads). Devbox names and the thread IDs used by scripting commands will not match. For archived or missing sessions, use dvb agents to review the available restore or recovery action. Don't run raw claude --resume inside the machine for a managed thread: it can start a competing Claude process for that conversation.

If you exit an empty new thread cleanly, the CLI asks whether to delete it and any devbox created specifically for it. An abrupt disconnect preserves it. Claude's initial trust or sign-in screens remain accessible by reopening its row in dvb agents.

Find a machine and open a terminal

Run dvb list to find your machines, then replace <devbox> below with the machine you want to use:

dvb connect <devbox>

To keep a named shell for a particular task, use dvb connect <devbox> -n server.

Named terminal sessions persist and replay output when you reconnect. Use dvb sessions to list, rename, or end them. Interactive commands can ask you to select among multiple machines; scripts need an explicit target.

For a one-off command, use dvb connect <devbox> --command "npm test". For structured output and exact arguments, use:

dvb exec --project <project> --target <devbox> --cwd project --json -- npm test

Arguments after -- are literal. Use bash -lc explicitly for shell pipelines or expansion. --stdin forwards input, and Ctrl+C cancels that command.

Choose a terminal connection

Managed is the default terminal connection. For a direct connection, use dvb connect <devbox> --transport direct, which uses encrypted UDP for lower-latency interactive terminals. Direct and Managed connections attach to the same named sessions. Direct mode requires the matching installed component and current machine support; if either is missing, the command explains the problem. One-off commands and detached creation use Managed.

Attach images and copy other files

Images in an open agent terminal

Native Codex and Claude interfaces can transfer PNG/JPEG images from your computer to the devbox. Use Codex's paste/drag attachment, Claude's stock image paste shortcut (Ctrl+V on macOS/Linux, Alt+V on Windows), or paste/drag absolute image paths. A batch is limited to 10 images, 20 MiB each, and 50 MiB total. Clipboard shortcuts carry one image. Custom Claude image bindings are not intercepted.

Pasting an absolute PNG/JPEG path that exists on your computer will upload that image; when you mean a file already on the devbox, type the path instead of pasting it. Invalid local images produce an error. Older machines may need a normal wake/update before image transfer works.

Images in a new-thread draft

The dvb agents composer also accepts PNG/JPEG images from the clipboard or a pasted local image path, with the same limits. It doesn't support general file attachments. Closing an ordinary unsent draft will preserve its text but remove its local images; add them again when reopening. Images already retained by Retry failed start remain with that request.

Other files

Other files and Codex @ picker results are not uploaded automatically. Copy them explicitly, then give the agent their remote path:

dvb cp <local-path> <devbox>:<remote-path>

This copies a local file or directory into the machine. Relative remote paths start at the project working directory. Use desktop Files for browsing and downloads.

Ports and machine actions

Use dvb ports to list ports, dvb ports fwd <devbox> <port> to allow forwarding, and dvb ports stop <devbox> <port> to disable it. For stable public addresses, see Project URLs, including the dvb url commands.

Commit and push code or download useful files before destruction. For scripting, use the project and resource operations in Agent command reference.

Account commands and troubleshooting

Use dvb whoami to check your account and dvb logout to sign out locally. dvb uninstall will remove local CLI state without destroying remote machines.

To repair agent sign-in, run dvb setup --agents on your computer. Use this for managed Codex authentication instead of running codex login or codex logout inside a devbox.

To report a problem, run:

dvb report-bug "The port menu stayed empty after reconnecting."

For a longer report, pipe text into dvb report-bug --stdin. The report will go to the same queue as Send feedback in the desktop app, with CLI version, platform, and available signed-in account details. It won't automatically include repository files, environment variables, or your working directory.