Use boxes.dev on your phone

The mobile app lets you check on agent work, reply, inspect files, and open a shell while you're away from your computer. Tasks started from your phone run on cloud machines, and a thread's messages and agent work are shared across mobile, desktop, and the CLI, so switching devices continues the same conversation.

Install and open a project

1. Install the mobile app on iOS or Android.
2. Sign in to your boxes.dev account.
3. Open your project, then tap a thread to read the agent's progress or reply.

Projects are ordered by recent thread activity. Projects you archive from Manage projects... in the desktop app won't appear here until you unarchive them. The app remembers the last project you opened. Thread-list rows show Git-change counts inline and a live devbox status dot at the right; sleeping devboxes show a timestamp there.

If you do not have a project, use desktop or local-agent setup, or open the boxes.dev website on your phone and choose Create from GitHub. See Choose how to set up your project.

Browsing the thread list, reading archived conversations, and editing an unstarted draft won't wake a machine. Opening a live thread will connect to the devbox or Template box where that conversation runs.

Choose a project from Home to open its conversations. Select the image to enlarge it.

Start or continue a task

1. Open a project and tap the new-thread button to start a task on a new devbox.
2. Choose Codex or Claude, write your request, add attachments if useful, and tap Send.

Long-press the new-thread button to open its menu. In a project with a personal Template box, choose New thread on template to work on the environment that future devboxes will inherit. Projects created from a Team Template offer only a new devbox. If a project does not support devboxes, tapping the button will open a Template-box draft instead.

To add a conversation to an existing devbox, choose New thread inside its group; the agents will share that machine's files.

The last Codex or Claude choice becomes the default for your next draft on mobile, desktop, and dvb agents. Open the model menu for available model, reasoning, speed, and Claude permission choices.

Use the attachment menu to add photos or files, including ZIP archives. Files can be up to 50 MiB each and 100 MiB per message. Check that the attachments appear in the composer before sending. During an active Codex response, use Steer to send attachments; Queue doesn't accept them.

Tap Dictate (the microphone beside Send or the agent's Stop button) to speak your request. On first use, tap Start dictation and allow microphone access. Your audio will be sent to OpenAI to turn it into text. Words appear live in your draft; tap the microphone again to finish, then review, edit, and Send. You can keep typing and adding attachments while speaking. Dictation never sends automatically. The microphone is highlighted while listening and shows a spinner while connecting or finishing. Leaving the thread or putting the app in the background 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 phone's settings. Update the mobile app from the app store if Dictate is absent.

After sending a follow-up, you can return to the thread list. boxes.dev will keep the message queued while the machine wakes or the agent accepts it.

Tap the copy button beside your message's or a final reply's timestamp to copy its text. To try a different direction from a completed reply, tap the vertical three-dot button beside its timestamp. Choose Fork in current box to share the same files, or Fork into new devbox to copy the box's current files into a separate machine. The new chat will include the conversation through the chosen reply; the files won't rewind to that point. You can also continue from the latest reply through the header menu. Wait for the agent to finish before forking; until then, the menu will show these choices dimmed and explain why. Unsent text and attachments will stay with the original chat.

To find a word or phrase in the open thread, choose … → Find in thread in the header and type your query. Use the up and down arrows to move among highlighted matches in conversation order. Find ignores capitalization and Markdown formatting, and searches your messages and final replies, including older messages. When a match is in older messages, Find will open that part of the thread with Load later messages below it; tap it to load the messages that follow. Tool output and intermediate commentary aren't searched. A + after the count means more matches are available, or that the newest messages are still being prepared for search; their matches will appear on their own. Tap × to close Find; your draft will stay in place.

When you choose Fork into new devbox, the new chat will open while the devbox is being created. Send messages to queue them; the agent will receive them when the copied conversation is ready. You can leave the chat while they wait.

Respond while work is running

Choose Queue to send a follow-up after the current work, or Steer to give the agent a correction during its response. For Codex, Steer now will interrupt the current response and start the oldest queued follow-up; the remaining messages will stay in order. Stop will stop the current response but leave Codex's queued messages available to run afterward. Unsent text and attachments will stay in the composer. See Start and continue a thread for the full Queue, Steer, and Stop behavior for each agent.

Queued Claude follow-ups appear at the end of the scrollable conversation. Once they reach the devbox, tap a message's delete button to remove it, or Edit queued prompts below the queue to return them to the composer. You can scroll through long queued messages while the composer stays available.

If a Codex message fails to send, its text and attachment names stay in the conversation. Tap Restore to bring them back alongside your current draft, or tap the dismiss button to remove the failed message.

If the agent asks a question or requests a permission while working, the request will appear in the conversation with its choices or input field. Answer it using the controls shown with the request. See Answer the agent's questions for each agent's question behavior and Agent permissions for what allowing a permission request changes.

Codex question forms show all questions together in the conversation. Tap an option to send a single choice answer immediately. For written answers or a set of questions, use the form's submit button. You can scroll away and back without losing unfinished answers. If Codex finishes working before you send an asynchronous answer, your edited answer will return to the composer.

If Claude is open in a terminal on your computer, you can still read its progress on mobile. To reply from your phone, choose Take over and confirm. This will close the terminal session and make the mobile composer editable. Unsent terminal text will be lost; your mobile draft and attachments will remain. Use Interrupt if you only want to stop the current response and leave control with the terminal. If Claude has finished replying but is still waiting for a background command, only Take over will be available, and taking over will stop that command. Claude will see that the command stopped, so you can ask it to run the command again.

Check the agent's rate-limit indicator for the latest available reading. That reading remains visible while the machine sleeps and updates when a newer one arrives.

If a connected MCP tool needs sign-in, follow the notice to Integrations → MCPs in the desktop app.

Read the agent's response and continue the conversation from your phone. Select the image to enlarge it.

Review files and use a terminal

Tap a file or diff link in the conversation to inspect the agent's work. Text files show syntax highlighting, and diffs show added and removed line counts. Use the page, zoom, and fit controls for PDFs. Files without a mobile preview will download directly. Large downloads may open in your browser and will keep their original filenames.

Open an inline screenshot or a screenshot file link, then swipe left for the next image or right for the previous one. You can also use the arrow buttons. The viewer will load older screenshot history as you browse across messages. Pinch or double-tap to zoom; dragging a zoomed image will pan it. Inline images and screenshot file links appear together in conversation order.

To see everything that changed on a devbox, tap the Devbox pill at the top of the conversation. It lists each repository's branch, merge conflicts, unpushed commits, and changed files with their added and removed line counts. Tap a file to open its diff. A warning icon in the pill or the thread list means a repository has unresolved merge conflicts.

Use desktop for the full file tree, workspace uploads, inline review, Git staging and commits, and port management.

Tap the terminal button for a shell on the thread's machine. Use the accessory controls for Ctrl, paste, and special keys. If the shell exits, choose Reopen shell. If the thread's machine is unavailable, return to the thread and reopen Terminal from there.

Organize or finish work

Tap Search messages in all threads above the list on Home or in a project to find an earlier conversation by its title or messages. Search covers your own Codex and Claude threads across all projects, including archived conversations, and shows excerpts of matching messages. Tap a result to open it. If the result matched a message, the thread will open with your search in Find in thread and the first match highlighted. See Search your threads.

Open a thread's menu to rename, pin, mark unread, mute notifications, archive, restore, or delete it when those actions are available. Mark unread will keep the thread unread on both mobile and desktop until you reopen it. A muted thread will not notify you when its agent finishes, and that finished turn will also clear a Mark unread marker. From a devbox group, you can put an idle devbox to sleep when you want to return to it later, or choose Rename devbox to show a name of your choice instead of its first thread's title.

If you want to remove a devbox, commit and push code or download any files you want to keep before choosing Destroy + archive. This will permanently delete the devbox's files and preserve its conversations as archived history. Review any warning about local changes or unpushed commits before confirming. To archive only a secondary conversation and keep the devbox, use Archive thread on that conversation.

To restore archived work, choose Restore thread and the offered destination. Projects with a personal Template box offer that machine or a new devbox; Team Template member projects offer a new devbox from the current saved version. Restoring a conversation won't recover a destroyed devbox's files.

Update the source for future devboxes

If you changed a personal Template box and want future devboxes to inherit those changes, open a thread on it and choose New snapshot from the header menu. The Template box will briefly become unavailable during capture.

Settings and connection problems

Settings and notifications

Open Settings to check usage, share your invite link or QR code, change your theme or font, or turn the unread app badge on or off. Under Appearance, choose Compact, Medium, or Large for thread text; Medium is the default. Tap a notification to open its thread, even when the app is closed.

Under Coding agents, open Agent accounts to choose, add, re-authenticate, or remove the Codex and Claude accounts your devboxes use. When one of those accounts needs you to sign in again, a banner shows at the top of the app; tap Reconnect to fix it. See Connect Codex and Claude for the sign-in steps.

Settings also includes the Help center, release details and refresh controls, sign-out, and account deletion. Account deletion is permanent; read Your data and credentials before proceeding.

To use another boxes.dev account on the same phone, tap Add account with Google in Settings (or Add account with Apple on iPhone) and finish signing in. The account you're using will stay open until the new one is ready, and the app will then switch to it. Your first account stays signed in: Settings will list it under Signed in as, and tapping it will switch accounts without signing in again. Sign out will sign out only the account you're using and open another signed-in account if there is one. Your phone will get notifications from every signed-in account; see Notifications.

Reconnect or retry a message

If Can’t connect appears, restore your internet connection or use Try again. The app will also retry automatically and retain already loaded project data during reconnects.

If the connection drops while a new draft's first message is sending, the app will keep it pending and send it after reconnecting. After about 30 seconds without reconnection, it will return the message to the composer for retry.

If you close the app after tapping Send and the message hasn't reached boxes.dev yet, reopening will restore the draft and its attachments. The restored draft is not resent automatically; tap Send again when you're ready. Once boxes.dev has accepted the message, the work continues whether or not the app stays open.