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. If you lose your place in a long list, choose the crosshair button next to it. The sidebar will scroll to the thread you have open and expand any section, folder, or devbox that hides it. The crosshair is hidden when the sidebar is too narrow, so widen the sidebar if you don't see it. The search button 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.

Once you've sent messages in three threads (not counting project setup threads), Code on the go! appears above your account at the bottom of the sidebar if you haven't signed in to the mobile app. Scan the QR code to download the mobile app, or choose X to dismiss the banner for this account on this computer. Signing in on mobile will also hide it.

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. Choose Archive to hide a project you aren't using from the project selector and the mobile app without changing its machines or threads; it will stay on this page under Archived until you choose Unarchive. 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, mute notifications, 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.

Use Dictate (the microphone beside the composer controls) to speak your request to Codex or Claude. On first use, choose Start dictation and allow microphone access. Your audio will be sent to OpenAI to turn it into text. Words appear live in your draft; click the microphone again to finish, then review, edit, and Send. You can keep typing or adding attachments while speaking, and dictation never sends automatically. The microphone is highlighted while listening and shows a spinner while connecting or finishing. Switching threads or hiding the window stops capture and keeps the text already in your draft. The agent's Stop button still controls its work.

Recordings stop after three minutes, and frequent use is limited to 120 starts per account in an hour. If the connection fails, review any words added to your draft before sending. If microphone access was denied, allow it for boxes.dev in your computer's settings. Update the desktop app if Dictate is absent.

Open a screenshot in an agent's reply to view it at full size. Press the left or right arrow key, or click the preview's arrow buttons, to browse images across messages. Inline images and screenshot file links share one gallery in conversation order. Going back past the oldest loaded screenshot will load older messages automatically, skipping messages without images. Navigation will also load missing messages between screenshots. At the newest image, going next will return to the oldest image discovered so far. Press Escape to close the preview.

An agent may point you to a control or setting with a blue pill in its reply. Hover the pill to see where the item lives, then click to reveal and highlight it. A settings page or menu may open, but you'll still choose whether to press the highlighted control or change a setting. Opening Template box details follows your usual Auto-wake preference. After a page detour, choose Back to thread to return to the conversation at its bottom; it won't restore your exact position in an older reply. Press Escape to dismiss a highlight. On mobile, tap a reference to learn where to find the item on desktop. References in shared or read-only conversations can't reveal your own controls, and unavailable items will have an explanation.

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.

An agent can also put an interactive visual, such as a chart or a small simulation with controls, in its final reply when a visual would explain something better than text, and you can ask for one. The desktop and mobile apps run the visual where it appears in the reply; in a web browser, choose Show visual to run it. Use the visual's controls to open it in your browser, expand it, or hide it. A hidden visual will stay hidden on that device until you choose Show visual. Changes you make inside a visual last only while it's on screen, so scrolling far away or reopening the thread starts it fresh, and so does expanding it in the mobile app. Visuals keep working while the devbox sleeps, and older versions of the app show them as ordinary links.

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. Ctrl+G opens Go to line only while Files has focus, so click in the file or the file tree first.

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.

If the browser doesn't show the Google sign-in page, or you closed its tab, choose Open in browser to open it again. To use a different browser on this computer, choose Copy link and paste the link there.

Once more than one account is signed in, the account menu shows Switch account instead. To switch, choose Switch account and click the other account. The app will open that account's last project, with no new sign-in. To add more accounts, choose Add another account at the bottom of the Switch account menu.

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 shows neither Add another account nor Switch 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 an update fails to install, the app won't download that version again on its own; choose Check for Updates… in the app menu to try again. Newer versions will still download automatically.

If you close the main window, choose File → Show Workbench to bring it back.