Tour the desktop app

In the desktop app, select a thread on the left to send instructions and read your agent's replies in the center. Open tools from the titlebar to inspect files, run commands, or test the app on that thread's devbox. When you're ready to give an agent a task, Your first task walks through a complete change.

The numbered labels below match the screenshots. The desktop app has been updated since these screenshots were taken, so some styling differs and one control has moved; the text points this out where it matters.

Find your way around

The desktop sidebar with labeled project, devbox, thread, integration, and settings controls. Select the image to enlarge it.

The sidebar starts with the project selector (A1), where you switch projects or add a new one, and New devbox + thread (A2), which starts a task with Codex or Claude on its own cloud machine. Use the back button beside the project selector to retrace earlier selections — after an integrations or settings detour, it returns you to the thread you were viewing. The search button next to it finds earlier conversations by their text; see Search your threads.

The list below groups your work. Folders (A3) group devboxes by purpose, such as feature work or bug fixes. Expand a devbox (A4) to see its threads; threads on the same devbox share files. Select a thread (A5) to open it — a blue dot marks an unread update.

Further down are the project's shared features. Integrations (A6) connects your tools and services, including MCPs and agent plugins. Open Project URLs (A7) to give your app a stable public address and choose which devbox serves it. Automations (A8) sets up repeatable agent tasks with a schedule or another trigger. Template box (A9) opens the project's Template box page: update the starting environment there, save snapshots for future devboxes, and choose New thread on Template box to work with an agent on that machine. A Member project created from a Team Template has no Template box page, and the New thread on Template box shortcut doesn't apply there. Settings (A10) and Help and feedback (A11) sit at the bottom.

Open the project selector to switch projects or choose New project.... Manage projects... lists your projects and setups in progress; choose Open to return to one. Before choosing Delete, read what project deletion removes. When your team's access settings allow it, Teammates' projects opens their work in a read-only view, and team admins also have a Team Templates management entry; to create your own project from a template, use New project....

Right-click a thread to rename, pin, mark unread, or archive it. Devboxes, files, and other items have right-click menus too; an unavailable action will explain what needs to change first.

Work with your agent

An agent conversation with labeled reply, model, usage, sharing, and Git review controls. Select the image to enlarge it.

The thread header names the conversation you have open (B1). Open Agent permissions (B2) to choose which boxes.dev actions agents may take on this devbox — creating devboxes and threads, for example. Share and the ••• more-actions menu (B3) are separate controls: use Share to share the conversation with teammates, and ••• for other thread actions. The header's GUI and CLI buttons switch between the graphical conversation and the agent's terminal view.

The conversation (B4) shows the agent's replies and progress; open its file links to inspect the work, or open the changed-files summary (B5) to review what a response modified. Type your request in the reply box (B6), also called the composer: use + to add attachments and ↑ to send, and keep sending corrections or new requests there to continue the same thread. You can also choose the model and its reasoning effort (B7), check how much of the conversation's context window is in use (B8), and open the usage gauge (B9) to see remaining agent usage and when limits will reset.

When an agent includes a Mermaid code block, the chat displays a diagram. Use its controls to copy the source, expand and zoom, or download it as an SVG. It loads when the agent finishes the block. If the diagram cannot be rendered, you can still read and copy its source. Diagrams also appear in mobile chats, with source copy and an expanded preview.

On the right, the review pane (B10, labeled Git changes in the screenshot) is the same Git/Review surface the titlebar opens: it shows changed files and diffs, with green marking additions and red marking removals. The expand control (B11) gives a file or diff more room while you review it.

Expand Settings in the sidebar when you need to change configuration:

• Configure agents... manages your Codex and Claude accounts and API keys.
• Desktop app settings... controls preferences on this computer. To show which agent owns each thread, enable General → Thread List → Show agent logos.
• Project settings controls project behavior, including defaults for new devboxes.

Run and review the work

The titlebar tools follow the selected machine. Select a devbox's thread, or open the Template box page, and Files, Git/Review, Terminal, Browser, and Ports will use that machine.

The desktop app with labeled machine tools and Browser review controls. Select the image to enlarge it.

The titlebar starts with the machine's status (C1) — open the menu to sleep or wake it — and its resource meters (C2): hover for CPU, memory, and disk usage, or click to inspect running processes. Ports (C3) opens your app running on the devbox in your laptop's browser, and Git/Review (C4) shows the branch and change counts; open it to review diffs, stage files, and commit.

Files (C5) browses, searches, previews, and edits files on the devbox. Terminal (C6) runs commands there; use separate tabs for servers and tests. Opening Terminal starts a session if the devbox doesn't have one, and closing the last tab also closes the pane. Closing a terminal tab ends that session, but closing the desktop app doesn't — open sessions are preserved and their tabs restored when you reopen it. Browser (C7) opens a browser on the devbox itself, so you and your agent share the same pages and signed-in session. Use Ports when you want to test in your laptop's browser, and Browser when you want the same session as your agent.

From the Browser you can also review pages with your agent: enter review mode (C8), click an element and write your feedback (C9), then choose Done and send the saved comments from the thread's reply box (C10). Review a page with your agent walks through it.

C11 is the switch to the agent's terminal view. In the current app it has moved to the thread header's GUI/CLI control described above.

The Files, Git/Review, Terminal, and Browser panes sit beside the conversation; drag the pane boundaries to make more room. Files, Git/Review, and Browser can also expand into a larger view, and each devbox remembers the last side pane you used.

If the machine tools are missing, you're likely on Settings, an integration page, or a teammate's shared thread. Those pages don't select one of your machines; return to your own thread, or the Template box page, to get the tools back.

Useful keyboard shortcuts

Hold Cmd or Ctrl to see number shortcuts for the first nine eligible visible threads. On Windows and Linux, while Terminal is focused, Ctrl+1 through Ctrl+9 and Ctrl+P go to the shell instead.

Open your account menu at the bottom left and choose Keyboard shortcuts to see current bindings and rebind them. Custom bindings need Cmd or Ctrl, cannot use Alt or conflict with another binding, and are saved per platform to your account.

Switch between accounts

If you use more than one boxes.dev account, such as a personal account and a work account, the desktop app can stay signed in to both. Open your account menu at the bottom left and choose Add another account, then finish signing in with Google in your browser. Your current account will stay open until the new one is ready, and then the app will switch to it.

To switch later, open the account menu and click the other account. The app will reload as that account and open its last project, with no new sign-in. Log out will sign out only the account you're using; if another account is still signed in, the app will switch to it. Desktop notifications and unread markers follow the account that's open.

If the account you add doesn't have a project yet, the app will open setup for it. To go back to your other account, click the account email at the top right of the setup screen and choose that account.

If your account menu doesn't show Add another account, update the desktop app.

Find help and updates

Choose Help and feedback at the bottom of the sidebar for troubleshooting tips or to send feedback. Choose Help center in that dialog to open these guides in your browser.

When an update is ready, use the titlebar's restart-to-update action or the app menu. If you close the main window, choose File → Show Workbench to bring it back.