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 desktop app is available for macOS and Linux. The main Mac download is for Apple Silicon and requires macOS 12 or later. Copying a local PostgreSQL database with the included tools requires macOS 13 or later.

The screenshots below use numbered labels to connect each control with its explanation.

Find your way around

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

The project selector at the top of the sidebar (A1) switches projects or adds a new one. Reopen the sidebar to switch projects when it is hidden. New thread (A2) below the project selector starts a task with Codex or Claude on its own cloud machine. Use the paired Back and Forward arrows beside the sidebar toggle in the titlebar to retrace earlier selections. Returning to a thread restores the reply you were reading; if you were following the latest output, you'll return to the bottom. Each arrow is disabled when there is nowhere to go in that direction. When the sidebar is narrow and you've zoomed out, the arrows are hidden if the controls won't fit. Widen the sidebar to bring them back, or press Cmd+[ and Cmd+] to go back and forward. If you lose your place in a long list, choose the crosshair beside the history arrows. 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 beside the project selector finds earlier conversations by their text; see Search your threads.

The work list groups your threads. 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 to open it — a blue dot marks an unread update (A5).

Below the project selector, New automation opens the automation editor. Coordinator appears here when available. The sliders beside the project selector open Project settings. Integrations (A6) lists your connected tools and available services, including MCPs and agent plugins; select a row to open its settings. Below Devboxes and Automations, expand Project to find tools and sharing. Project URLs (A7) lists stable public addresses and offers New Project URL. Open a URL to choose which devbox serves it. Public links appears when the project has active links; its page lets you open, copy, or stop sharing them.

Shared with me lists conversations teammates have shared with you across projects. Select a nested thread to read it, use the chevron to collapse the threads, or select the heading to open the full list. Expand Shared by me to manage this project's shared threads and access requests. These rows appear when they have items.

Automations (A8) sets up repeatable agent tasks with a schedule or another trigger. Under Project, select Template box (A9) to open its page, or use the chevron to expand its threads. Hover the row for New thread on Template box and its … menu, where you can open its terminal, save a snapshot, or put it to sleep. A managed project created from a Team Template has no Template box page, and the New thread on Template box shortcut doesn't apply there. Your account menu (A10), box-hours usage icon, and Help and feedback (A11) stay fixed at the bottom of the sidebar. The project selector and New thread will stay visible at the top as you scroll. Your first name appears beside your avatar, followed by your team name in a lighter color. If your profile has no name, your account label appears instead. Hover over or click the usage icon just left of Help for usage details.

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/CLI control switches 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 agent account control (B9) to check the connected account or API key. When the account provides usage limits, the gauge shows remaining usage and when limits will reset.

Use Dictate (the microphone beside Send) 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. While dictation listens, the microphone turns solid blue and the reply box has a blue outline. Your words appear live at your cursor if you were typing in the reply box, otherwise at the end of your draft. A blue caret with a small microphone above it shows where the next words will go, and the words from this recording stay highlighted while you speak. You can keep typing or adding attachments while speaking. The microphone shows a spinner while connecting.

Click the microphone again to stop listening. It will turn off right away, and any last words will appear in your draft a moment later. Then review, edit, and Send. If you click Send or press Enter while dictating, the last words will be added before your message is sent; dictation never sends on its own. 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 your place in the conversation. 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.

Agents can also show you images and videos in a final reply, such as screenshots of a change or a recording of a test. They appear as a row of previews with captions, and when there are more than four files, the last slot shows how many more there are. Select a preview to open it, then use the arrow buttons or arrow keys to move between files. Hover or focus a preview for its Download shortcut, or choose Download all below the row to save every file separately, including those behind + more. Right-click an image for Download, Copy image, and Copy link. After downloading, Show in folder will reveal the saved copy on your computer. Published copies don't retain their original devbox paths, so they can't open in the Files pane. The current desktop app saves directly to Downloads; update the app if downloads open your browser. Videos will play only when you start them. Images that an agent looks at while it works stay inside collapsed activity. Ask the agent to show you any screenshots you want to see in its reply. Older versions of the app show these files as ordinary links that open on boxes.dev.

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. Pop out Git pane (B11) gives a file or diff more room while you review it.

Open your account menu at the bottom left and choose Settings…, or press Cmd+, (Ctrl+, on Windows and Linux). Choose a section in its sidebar without leaving your conversation:

• General controls appearance, startup layout, thread sorting, agent logos, and your idle-sleep preference.
• Agents manages Codex and Claude accounts, API keys, and reply defaults.
• Notifications, Connections, Browser, and Terminal group their related preferences. Labels distinguish this computer from all your devices.
• Account, Team and members, Integrations, and Billing & usage contain personal and team administration. Team admin sections appear for admins.

Related settings links to the selected project's Project settings and its source Team Template settings. With no source template, the second link opens the template collection. With no project, the first opens your project list. These links open the existing editors; Back returns to Settings. The sliders beside the project selector also open Project settings.

Older desktop versions will open device preferences in their existing separate window; update the app to edit them in the unified pane.

Choose a category in Settings or open the related project and Team Template settings. Select the image to enlarge it.

Run and review the work

The titlebar tools follow the selected box. Select a devbox's thread, or open the Template box page, and Files, Git/Review, Terminal, Browser, and Ports will use that machine. You can keep localhost on one devbox while you work elsewhere; its amber computer icon in the sidebar marks that choice. The Ports menu still describes the devbox you are viewing.

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.

Use the thread header's GUI/CLI control (C11) to switch between the graphical conversation and the agent's terminal view.

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

Press Cmd+B (Ctrl+Shift+B on Windows and Linux) again to reopen the sidebar, or use the sidebar button beside Back and Forward. Your open conversation will stay in place. Each project remembers the sidebar's visibility and width on this computer.

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.

Cmd+F (Ctrl+F on Windows and Linux) searches what you're looking at. In a conversation, it opens Find in conversation. On a page without a conversation, such as a Team Template's page or Project settings, it opens a find bar at the top right of the window. In the workbench, click in the page first; otherwise Cmd+F opens thread search. The bar finds text on the page, including what you've typed in fields and script editors. Press Enter or Shift+Enter to move between matches, and Escape to close the bar. The bar doesn't search inside dialogs such as Settings, and it needs the latest desktop app.

Back and Forward use fixed browser-style shortcuts. While Terminal or Browser has focus, Cmd+[ and Cmd+] keep switching its tabs instead.

While Terminal has focus, Cmd+W (Ctrl+Shift+W on Windows and Linux) closes its current tab. With a thread selected, the same shortcut closes its view and shows No thread selected. Reopen the thread from the sidebar or choose Back; your draft and any running work stay with it. To archive a thread, right-click it and choose Archive.

Open Settings → Keyboard shortcuts to see current bindings and rebind customizable actions. 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.

The app downloads updates in the background. When an update has downloaded, the titlebar shows Click to update. Click it, or use the app menu, to restart into the new version. If you quit instead, the update will install and the new version will open next time. The button is grayed out while project setup is reading files from this computer. If boxes.dev needs the new version before it can continue, it will ask you to restart once the update has downloaded.

On a Mac, if a new version still hasn't downloaded two hours after the app learned about it, the titlebar shows Update available instead. Click it to download the update now. If the download fails, the button will change to Update failed. Hover over it to try again, or to download the latest version from boxes.dev and install it yourself.

Both buttons turn from blue to yellow once the app has been behind for a day or has missed two releases, and to red after three days or three missed releases.

If an update keeps failing, the app will wait six hours before downloading that version again on its own. Choose Check for Updates… in the app menu to try sooner. Newer versions will still download automatically.

On Linux, the AppImage updates itself the same way. If you installed the .deb or .rpm package, your system updates will keep the app current, because the package adds the boxes.dev repository. When the app needs a newer version before it can continue, it will show the command to run, such as sudo apt update && sudo apt install --only-upgrade boxes-dev. Run it in a terminal, then choose Restart App.

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