Appearance
File Explorer
The desktop and Android apps include a right-side sidebar for browsing the files in a project's working directory on the daemon node that owns it, plus file operations (create, rename, move, copy, delete, download) and host upload/clipboard integration. The git changes panel and built-in editor are tracked separately.
Where it lives
The right sidebar is part of the Workspace view (/workspace). It also appears in Chats and for SSH sessions; see Panels per view.
- Desktop (md+): a 288 px aside on the right of the pane area. It is collapsed by default; a collapse button hides it and a small toggle on the right edge of the pane area re-opens it. The open/closed choice is remembered per layout group (a session, or the sessions sharing its panes) for the current app session and resets to collapsed when the app restarts. Drag the handle on the sidebar's left edge to resize it (220-560 px); the width is remembered across restarts via
localStorage["clusto-right-sidebar-width"]. - Mobile (< md): a sheet drawer that slides in from the right. The trigger lives in the workspace tab bar's trailing slot. Safe-area insets (
var(--sat),var(--sab),var(--sar)) are honored so the sheet sits clear of system chrome on Android.
The sidebar shows up to three tabs: Files, Git, and Run (on mobile, a dropdown picks the panel). The last open panel is remembered per device. Which tabs appear depends on the view; see Panels per view. The Git panel and Run panel are documented separately.
Panels per view
Each view keeps its own set of panels:
| View | Default panels | Notes |
|---|---|---|
| Terminals | Files, Git, Run | Run types commands into the focused terminal, so it is Terminals-only. |
| Chats | Files, Git | Git shows when the chat works in a project root. |
| SSH | Files | Lists files on the cluster node the ssh client runs on. |
To change the set, use the sliders button in the sidebar header: it shows a checkbox per panel for the current view, and the last remaining panel cannot be unchecked there. You can also open Settings > Appearance > Right sidebar; turning every panel off for a view hides the sidebar in that view. The panel configuration syncs with your other preferences; the last open panel is per device.
The collapsed sidebar is a slim rail with one button per enabled panel, so any panel is one click away. Press F1 and run Toggle right sidebar (default shortcut Ctrl/Cmd+Shift+E), or Show Files in sidebar, Show Git in sidebar and Show Run in sidebar. On phones the sidebar opens as a sheet: from the terminal switcher button in Terminals and SSH, and from the header menu (Chat files) in Chats.
What it shows
The Files tab lists the contents of the active project's working directory. Folders sort first, then files, both alphabetically (case-insensitive). The .git directory is hidden. Click a folder to expand it; children load lazily on first expand and are cached until the page is refreshed or the project changes.
A .. row stays at the top of the tree. Select it to browse the parent directory on the same node inside the sidebar, keeping the current workspace open. Continue up with .. or select folders to browse into them, including sibling directories. The header shows the current path. Select Return to project root in the header, or browse back into the project's directory, to restore its tree.
Outside the project tree, selecting a file opens a preview. Project file operations, uploads, and drag-to-move are unavailable while browsing these directories. Use the separate whole-filesystem Files view when you need to manage files outside the project.
A refresh button in the panel header re-fetches the root listing without clearing children of expanded subdirectories.
Auto-refresh
While the Files tab shows the project tree, the explorer keeps it in sync with the disk automatically: changes made outside the app (a terminal session, git checkout, a build, or another node) appear without pressing refresh. The daemon watches the project's working directory (recursively, via the notify crate), debounces a burst of events, and pushes a coarse project_files_changed. The app coalesces those and re-lists the directories it has cached - the root plus any expanded subfolders - so the whole visible tree updates.
The watch is established when the Files panel mounts (and re-targeted when the active project changes), and torn down on unmount, on project switch, and when the connection drops. .git internals and the daemon's own atomic-write temp files (*.tmp) are filtered out so routine churn doesn't trigger refreshes.
In cluster mode the watch is routed to the node that owns the project: the owner runs the watcher and streams change events back over the peer transport (subscribe_project_files / project_files_changed), so projects hosted on a remote node auto-refresh just like local ones.
Selecting a file in the project tree opens it in the built-in editor as a tab on the focused terminal's pane in Terminals, or on the chat's pane in Chats (see Files for a chat). Files from a plain folder listing (SSH sessions, or browsing outside the project) open as editor tabs too. PDFs open in a preview card.
File operations
In the project tree, each entry has a kebab (⋮) menu, and the panel header has New File / New Folder / Upload files / Paste buttons for the project root. On touch devices the kebab is always visible; on desktop it appears on row hover and the same menu also opens on right-click. (Right-click is suppressed on touch devices, which restores the native context menu, so the kebab remains the touch affordance.) Available actions:
- New File / New Folder - prompts for a name and creates it in the chosen directory. Creation is exclusive: it fails if the name already exists.
- Rename - renames an entry in place (a same-directory move).
- Copy Full Path - copies the entry's absolute path on the daemon node that hosts the project.
- Copy Path from Project Root - copies the entry's path relative to the project's working-directory root.
- Drag to move (desktop) - drag a file or folder row onto another folder to move it there, or onto the empty root area to move it to the project root. Dragging a selected row moves the whole selection. The destination highlights when it can accept the drop. Clusto rejects drops into the current parent and prevents moving a folder into itself or one of its descendants. If both a folder and one of its children are selected, moving the folder carries the child with it only once.
- Copy / Cut → Paste - Copy or Cut stages the entry (or the whole selection, see below) on the clipboard; Paste drops every staged entry into the target directory. Cut performs a move and then clears the clipboard; Copy can be pasted repeatedly. Directories copy recursively. Pasting onto an existing name is refused (no clobber).
- Delete - removes a file, or a directory and everything inside it, after a confirmation dialog.
- Download - saves the file to a destination the user picks. In the native desktop and mobile apps it is streamed in chunks with no size cap (the 25 MiB binary-read limit does not apply); the web app fetches the file in one frame, so web downloads stay bound by the 25 MiB limit. Every platform asks where to save: the native Save-As dialog on desktop, the system SAF "create document" picker on Android (choose the directory and name; the streamed file is then moved into the chosen document), and
showSaveFilePickeron the web where the browser supports it - Firefox, Safari and Chrome on Android have no picker API, so those fall back to the browser's own download flow. iOS has no picker bridge yet and writes into Downloads. The daemon serves the file in 8 MiB windows (stateless ranged reads) and the app writes each window straight to disk in Rust, so the bytes never buffer whole in memory or pass through the webview. A toast shows download progress. A single file downloads as itself; a folder, or a multi-selection, downloads as one zip (below).
Download as a zip
Download on a folder row, and bulk Download of a multi-selection, produce one zip instead of one save dialog per file. Folders are no longer skipped. A selection of a single file still downloads as that file.
- You pick the save destination first.
- The node that holds the files builds the zip in a private
<data_dir>/archivesdirectory (mode 0700, owner-only ACL on Windows). A toast reads "Zipping<name>.zip..." while it builds. - The node replies that the archive is ready and the app streams it in 8 MiB windows like any other download, with the usual progress toast.
The zip is named after the entry when one is selected (<entry name>.zip), or after the folder that holds them all when several are selected. Selections that share no folder use the project root's name, or files. Folders are added recursively and empty folders are kept. Symlinks below a selected folder are skipped, as are sockets, FIFOs and devices. Selections with the same name get a (2) suffix. Already-compressed formats (png, jpg, mp4, zip, gz and similar) are stored as is and everything else is deflated at a fast level; files of 4 GiB or more use zip64.
The node refuses a build that would leave less than 1 GiB free on the disk that holds its data directory ("not enough free space on the node ..."). The archive is deleted once its last window is read; one that was never finished is swept an hour later, on the next build. Archive requests need an admin credential: session credentials are refused, as for other file chunk reads. The project sidebar explorer still does not work in the web app.
- Copy to clipboard (desktop only) - copies a file to the host OS clipboard so it can be pasted in the host's file manager. The bytes are fetched from the daemon, staged into a temp file locally, then placed on the clipboard via the clipboard plugin. Files only; hidden on mobile.
Multi-select and bulk actions
Every tree row has a checkbox (always visible on touch, on hover or while a selection exists on desktop). Ctrl/Cmd-click toggles a row, Shift-click extends the range across the rows the tree currently renders (expanded folders included), and a plain click clears the selection and opens the entry. Ctrl/Cmd+A selects every visible row, Escape clears the selection.
While a selection exists the panel shows a bar with its size and bulk Download, Copy, Cut, Delete, and Clear buttons. Acting on a row that is part of the selection - from the kebab menu, the right-click menu, Ctrl/Cmd+C/X, or Delete - applies to the whole selection, and the menu labels carry the count (Delete (3)); acting on any other row applies to that row alone. Bulk delete asks once for the whole set. Bulk download of several entries produces one zip (see Download as a zip). Copy to the host OS clipboard stays single-file. Copy Full Path and Copy Path from Project Root copy every selected path as plain text, one path per line.
Press F1 to run either path-copy command from the command palette's Files group. The commands target the current selection, or the last-clicked file or folder when there is no multi-selection. The same group also includes Browse parent directory, which performs the .. action without requiring the Files tab to be open, and Return to project root to restore the project tree after browsing elsewhere.
Failures surface as a toast; the tree refreshes the affected directories on success. Each mutation carries a client-generated request_id that the daemon echoes back so the in-flight operation resolves precisely.
Uploading from the host
- Upload - the header's Upload files button (project root) or a folder's Upload menu item opens the system file picker and uploads the chosen files into that directory. The picker uploads individual files.
- Drag & drop from the host (desktop) - drag one or more files or folders from the host onto the explorer to upload them. Dropping onto a folder row uploads into that folder; dropping onto the empty area uploads into the project root. The active drop target is highlighted. A dropped folder is recreated with its whole tree, every file at its relative path.
- Paste (Ctrl/Cmd+V) - with a folder or the root selected, paste uploads any files or folders currently on the host OS clipboard (desktop) into that directory, keeping folder structure. When the clipboard holds no host files, it instead pastes the explorer's internal cut/copy clipboard (the in-project move/copy described above).
- Copy / Cut (Ctrl/Cmd+C / Ctrl/Cmd+X) - with a file selected, Copy places it on the host OS clipboard (and the internal clipboard for in-project paste); Cut marks it for an in-project move. Click a file, folder, or the empty root area to set the selection these shortcuts act on.
Uploads have no size cap. The app sends a file in 8 MiB windows, each acknowledged before the next is sent, and the upload toast shows a percentage. While it uploads, the file grows in a hidden part file named .clusto-upload-<uuid>.part next to the target; it appears under its real name only when the last window lands. A failed window deletes the part file. An app that quits mid-upload can leave a part file behind, which is safe to delete.
Each top-level dropped or pasted item uploads as one unit with a single progress toast (for example "Uploaded Foo (12 files)"). A name that already exists in the destination is suffixed (name (1).ext) so an upload never silently overwrites; for a folder the top-level name is suffixed. Symlinked directories inside a pasted host folder are skipped, and symlinked files upload as their target. Each uploaded file is chowned to the project's run-as user (see below).
Send files to a terminal
With a writable terminal focused, Clusto can attach images and documents directly to the current prompt:
- Paste (Ctrl/Cmd+V) - uploads files from the clipboard and types their quoted daemon paths into the terminal. The desktop app also understands files copied in the native file manager. If the clipboard has no files, Clusto pastes text normally.
- Paste image (Alt+V) - uploads clipboard images only. If the clipboard has no image, Clusto leaves other files and text untouched.
- Drag and drop - dropping one or more host files onto the terminal uploads them and types their quoted paths into the current command.
Terminal attachments are capped at 10 MiB per file. Clusto stores them under the daemon's session attachment directory, outside the project tree, and inserts a space after each path so you can keep writing the prompt. It does not submit the command automatically.
Attach menu: device, camera or node
The Attach file paperclip on the terminal key bar, the terminal context menu (right-click on desktop, long-press on a phone) and the F1 command palette all offer the same three sources (on iOS the device entry is split in two, see below):
- Files from this device (palette: Attach file from this device) - opens the system file picker. The chosen files upload next to the session and their paths are typed into the prompt, exactly like paste or drop. The 10 MiB per file cap applies.
- Take photo (palette: Take photo into terminal) - captures a photo and attaches it the same way. On Android and iOS this opens the native camera app. On desktop it opens an in-app webcam dialog with Capture, Retake and Use photo. macOS and iOS ask for camera permission the first time. On Linux desktop the webcam may be unavailable because the web view denies camera access; use Files from this device there instead.
- From a node (palette: Attach file from a node) - opens the cluster file picker, where you can switch nodes from the header. Entries on the session's own node are typed as their paths directly, folders included, so nothing is copied. Files on another node are copied over the cluster next to the session (10 MiB cap) and their new paths are typed. Folders from another node are refused.
On iOS the menu lists Photo library, Take photo, Files and From a node..., and each opens its picker directly: the photo library, the camera or the Files browser, with no second iOS sheet on top of the menu. iPhone HEIC photos picked from the library are converted to JPEG before they upload, so agents can read them. Android and desktop keep the entries above.
Wire protocol
The read side of the file protocol is below. All operations are scoped by project_id and validated against that project's working_dir before any IO is attempted.
ListProjectFiles
jsonc
// client → daemon
{ "type": "list_project_files", "project_id": "<uuid>", "path": "src" }path is interpreted relative to project.working_dir. null or an empty string resolves to the project root. The daemon validates the resolved path stays inside working_dir (canonicalize + ancestor check) and rejects path traversal with project_file_error.
jsonc
// daemon → client (success)
{
"type": "project_file_list",
"project_id": "<uuid>",
"path": "src",
"entries": [
{ "name": "components", "path": "src/components", "kind": "dir", "size": 0 },
{ "name": "lib.rs", "path": "src/lib.rs", "kind": "file", "size": 4096 }
]
}ReadProjectFile
jsonc
// client → daemon
{ "type": "read_project_file", "project_id": "<uuid>", "path": "README.md" }jsonc
// daemon → client (success)
{
"type": "project_file_content",
"project_id": "<uuid>",
"path": "README.md",
"content": "...",
"sha256": "abc123..."
}The sha256 is the lowercase hex digest of the raw bytes. The editor uses it for optimistic-concurrency checks on writes.
ReadProjectFileChunk
Backs the streaming Download action for files of any size. Each request seeks to offset and returns up to len bytes (the daemon caps len to its own 8 MiB per-frame bound); the client loops windows until eof, writing each to disk. The read is stateless (seek per request) with no total-size cap, so no whole-file copy is ever buffered in memory on either side.
jsonc
// client → daemon
{ "type": "read_project_file_chunk", "request_id": "d1", "project_id": "<uuid>",
"path": "build/artifact.bin", "offset": 0, "len": 8388608 }
// daemon → client (success) - `data` is base64-encoded
{ "type": "project_file_chunk", "request_id": "d1", "data": "...",
"offset": 0, "total_size": 134217728, "eof": false }A failed window answers with project_file_chunk_error (carrying the originating request_id). In-app preview of binary files is unchanged and still uses read_project_file_binary, which keeps the 25 MiB cap.
ProjectFileError
Returned when the project doesn't exist on this daemon, the path escapes the working directory, the file is missing, the file is binary (NUL byte detected in the prefix), or the file exceeds the 1 MB read limit.
jsonc
{
"type": "project_file_error",
"project_id": "<uuid>",
"path": "../etc/passwd",
"message": "path escapes project root"
}Filesystem mutations
The create / rename / move / copy / delete operations share one request/response shape. Each request carries a client-generated request_id; the daemon answers with project_fs_action_result (success) or project_fs_action_error (failure), both echoing that request_id. Paths are project-relative and validated against working_dir; create/move/copy refuse to overwrite an existing destination.
jsonc
// client → daemon (rename / move)
{ "type": "move_project_entry", "project_id": "<uuid>",
"from": "a.txt", "to": "b.txt", "request_id": "r3" }
// daemon → client (success)
{ "type": "project_fs_action_result", "project_id": "<uuid>",
"request_id": "r3", "path": "b.txt" }The full set of request types is create_project_file, create_project_directory, move_project_entry, copy_project_entry, delete_project_entry, and upload_project_file_chunk. See Protocol for every payload.
upload_project_file_chunk carries one window of a file: { request_id, project_id, upload_id, path, offset, data, last }, with data base64-encoded on the wire. Windows are sequential (offset equals the bytes already written, starting at 0) and at most 8 MiB each. The daemon appends each window to a hidden .clusto-upload-<uuid>.part file next to the target, created exclusively (no clobber), and answers every window with project_fs_action_result or project_fs_action_error. A failed window deletes the part file. When last is true the part file is moved into place under its real name and chowned to the run-as user.
The Tauri commands behind it are upload_project_file_chunk (sends one window), upload_host_file_chunk (reads one window of a local file and returns { len, total, last }), and list_host_tree(paths), which expands pasted host folders into their files.
Archive (zip) download
Zips use three requests and two replies:
jsonc
// client → daemon: build a zip of project-relative, contained paths
{ "type": "prepare_project_archive", "request_id": "z1",
"project_id": "<uuid>", "paths": ["src", "README.md"] }
// daemon → client (success)
{ "type": "archive_ready", "request_id": "z1", "node_id": "<node>",
"archive_id": "<id>", "total_size": 52428800, "file_count": 120 }
// daemon → client (failure)
{ "type": "archive_error", "request_id": "z1", "message": "..." }
// client → daemon: read one window of the finished zip
{ "type": "read_archive_chunk", "request_id": "z2", "archive_id": "<id>",
"offset": 0, "len": 8388608 }read_archive_chunk is answered with the existing project_file_chunk / project_file_chunk_error frames. The Files view uses fs_prepare_archive ({ request_id, paths, node_id? } with absolute paths) in place of prepare_project_archive. Requests are forwarded to the owning node (the project owner, or node_id); a forwarded build may take up to 30 minutes. The Tauri commands are prepare_archive, download_archive_to_path and download_archive_to_downloads.
Single-file download streams over the read_project_file_chunk / project_file_chunk messages above. The Tauri commands download_project_file_to_path (desktop, after the native Save-As dialog) and download_project_file_to_downloads (mobile, staging into app-private storage) pull the windows and write each straight to disk in Rust, emitting a progress event for the progress toast. On Android the staged file is then moved into the document the user picked in the SAF dialog. Copy to clipboard still reuses the 25 MiB binary read, then stages the bytes via the stage_clipboard_file command before handing the temp path to the clipboard plugin.
Multi-node behavior
When the project's node_id points to a peer other than the daemon that received the request, the daemon forwards the message over the inter-node WebSocket and relays the peer's response back to the client. This mirrors how ListOsUsers and GetDaemonLog behave for per-node operations. The client sees a single response - the forwarding is invisible. Filesystem mutations forward the same way and surface peer-unreachable failures as project_fs_action_error.
Standalone daemons (no cluster) always handle requests locally.
Limits and rejections
- Read size cap: 1 MiB. Files larger than this return an error.
- Binary files: any NUL byte in the first 8 KiB rejects the read.
- Non-UTF-8 text: the text read returns an error; previews of binary files use the separate binary read (25 MiB cap).
- Symlinks pointing outside the working directory: rejected by canonicalization.
- The
.gitdirectory is filtered from listings.
Run-as users
Reads and listings run as the daemon's own user; the security boundary is path containment, not user impersonation.
Creation and upload additionally fix ownership: when a project's run_as_users map resolves to an OS user for this node (node-keyed entry, falling back to the "*" wildcard - the same lookup sessions use), newly created files, new directories, and uploaded files are chowned to that user. This keeps files owned by the same user sessions run as, instead of the daemon's user.
The chown is a no-op when the resolved user already matches the daemon's effective uid, so single-user (non-root) deployments are unaffected. When the users differ it requires privilege - i.e. the daemon running as root - exactly like runuser-based session spawning. A chown that cannot be performed surfaces as project_fs_action_error rather than silently leaving the wrong owner. Ownership fixing is POSIX-only; on Windows it is a no-op.