Browse, edit, and transfer files

Open Files to read and edit files on your devbox, or to download a generated image or report to your laptop. Files displays the selected cloud machine's files, and your edits will change those files.

Find and open a file

1. In the desktop app, select a thread on the devbox you want to inspect, or select the Template box to inspect its files. If the machine is sleeping, wake it from the machine status control in the titlebar.
2. Open Files from the titlebar.
3. Browse the file tree and click a file to open it. The buttons above the tree let you return to the project directory, go up one directory, or open your home directory on the machine.

To find a file by name, press Cmd+P on macOS or Ctrl+P on Windows and Linux; the Search files field above the tree opens the same dialog. On Windows and Linux, Ctrl+P stays with the shell while Terminal has focus, so click outside Terminal first. To find text inside files, press Cmd+Shift+F or Ctrl+Shift+F.

Files shows the directory tree beside the selected file, with editing and download controls. Select the image to enlarge it.

Search the workspace

The search dialog has a Files tab and a Text tab, and switching tabs will keep your query. Files matches words anywhere in a name or path. For example, search for usage dashboard to find usage-dashboard.tsx. If there are no matches, press Enter to open the exact path you typed.

The Text tab searches file contents. Lowercase queries match any case by default; use the case, whole-word, and regular-expression controls to refine the search. Very broad searches may show only the first matches, with a notice when that happens.

Use arrow keys to move through results and Enter to open one; text results will open at the matching line. Press Escape to close the search and return to your original layout. If the Text tab says the machine needs an update, file-name search remains available; see Troubleshooting if the message doesn't clear.

Edit and manage files

Edit supported text files directly in Files. Your changes will save after you stop typing and before you switch files or close the pane; the file header shows whether the draft is saved, saving, or blocked by an error. If another process or your agent changes the file while you have unsaved edits, choose whether to reload the version on disk or overwrite it with your draft.

Use New file or New folder above the tree to create an entry. Check the destination in the dialog; use Change to choose another folder.

Right-click a file or folder for Rename, Move, Delete, and Copy path. You can also press F2 to rename a selected entry, or drag it to another folder to move it. Review the destination and confirm the move. Move keeps the name and doesn't overwrite an existing target or merge folders.

Before choosing Delete, save anything you need elsewhere. Deletion is permanent, with no Files trash or undo. Deleting a folder will remove all of its contents. To manage the folder currently at the top of the tree, navigate to its parent first.

If management actions show an update message, the machine needs a boxes.dev update before you can use them. You can still browse files, copy paths, and download supported files; see Troubleshooting if the message doesn't clear.

Upload and download

To copy a file from your laptop to the selected machine:

1. Drag the file from your laptop into the Files tree.
2. Point at a folder to upload inside it, or at a file to upload beside it. Empty tree space targets the directory at the top of the tree.
3. Check the destination shown while dragging, then drop the file. Watch its progress row; retry or dismiss the row if the upload fails.

Uploads can run in parallel. Each desktop upload can be up to 1 GiB, with up to 2 GiB of active uploads per user at once.

To copy a file to your laptop, choose Download in its header or right-click menu. After the download finishes, choose Open in Finder on macOS or Open in folder on Windows and Linux to find the saved copy.

Folder rows don't offer downloads. Ask your agent to create an archive, or create one in Terminal, then download the archive through Files. For finished code changes, use Git to commit and push the work instead of transferring files one at a time.

Use a file's menu to copy its path, download, rename, move, or delete it. Select the image to enlarge it.

Preview documents and media

Images and videos open in media previews. Click an image to enlarge it, then scroll to zoom and drag to pan. PDFs open in a viewer with page controls and zoom. Files detects the format from the content, so an incorrect extension doesn't necessarily prevent a preview. Download a file if it can't be previewed.

Markdown opens in Source for editing. Choose Preview in the file header to read the rendered document, including your unsaved draft, and return to Source to edit. Links to files on the machine open in Files, and local images appear in the document. Remote images remain linked placeholders instead of loading automatically.

Files shows the current file contents. To see what changed in Git, select Git/Review in a changed file's header. To ask your agent for changes to specific lines, use code comments.

Return to an open file

While the desktop app stays open, Files remembers the last open file for each machine. Threads on the same devbox share that selection, and switching to another devbox will restore the file last opened there.

Closing Files, opening a directory, or deleting the open file will clear that machine's remembered file. Reloading or restarting the desktop app will return Files to the tree.

Copy from your laptop with the CLI

With the boxes.dev CLI installed and signed in on your laptop, run:

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

Replace the placeholders with your laptop's file or directory, the devbox's name, and the destination path. Run dvb list first to see your machines' names. Relative remote paths start at the devbox's project directory. dvb cp only copies from your laptop into the machine; to bring a file back to your laptop, use Download in the desktop Files pane.