Appearance
Files (Whole-Filesystem Explorer)
The Files view is a top-level file manager for browsing and managing the entire filesystem of any cluster node by absolute path. Pick a node, then navigate it like a desktop file manager: breadcrumbs, an editable path bar, folder navigation, text/media preview, and full file management.
This is distinct from the right-sidebar File Explorer, whose file operations remain contained to a project's
working_dir. Use the sidebar's top..row or its F1 Browse parent directory command to browse parent directories within the sidebar. Open Files from the main navigation for full file management outside a project. The Files view has no project sandbox; see the security note below.
Capabilities
- Node selection - a reusable node picker lists the connected node plus its peers. Switching nodes re-roots the explorer on that node's filesystem.
- Browse - lists one directory level at a time, folders first. Starts at the node's default browse directory (the run-as user's home). The address bar shows the path as breadcrumbs (click a segment to jump there) next to Up and Home buttons; the pencil turns it into an absolute-path field (Enter to go, Escape to cancel). Rows show a type icon, modified time and size; on desktop the row menu appears on hover, on touch screens it is always visible.
- Preview - text files open in an inline editor; images, audio, video, and PDFs render in a media viewer (built from a
data:URL). - Edit - text files save with SHA-256 optimistic-concurrency: if the file changed on disk since it was opened, the save is rejected as a conflict.
- Manage - create file, create folder, rename, copy / cut + paste, delete (behind a confirm dialog), upload (file picker, no size cap), and download. Download always asks where to save - native Save-As on desktop, the system SAF picker on Android,
showSaveFilePickeron browsers that support it - and streams the file to disk chunk by chunk with no size cap, showing a progress toast. Folder rows have a Download item too: a folder, or a multi-selection, is downloaded as one zip (see below). On Unix, a folder created through this view inherits its parent directory's user and group, so a systemclustoddoes not leave a root-owned folder in a user's directory. A non-root daemon attempts this inheritance only when it owns the parent directory. - Multi-select - each row has a checkbox and the list header carries a select-all box plus the entry/selection count. Ctrl/Cmd-click toggles a row, Shift-click extends the range, and a plain click clears the selection and opens the entry. With a selection active the header shows bulk Download, Copy, Cut, Copy paths, Delete, and Clear buttons; the row menus act on the whole selection when the row is part of it (labels carry the count, e.g.
Delete (3)) and on that row alone otherwise. Bulk delete confirms once for the set, bulk download of several entries produces one zip (see Download as a zip below), and Copy paths joins the selected absolute paths with newlines. The selection resets when navigating or switching nodes. - Cross-node - every request carries an optional
node_id; when it targets a peer, the daemon forwards the request to that node and relays the reply (the same forwarding pattern used by the remote log fetch).
Limits
- Listings are capped at 5000 entries; very large directories show a "truncated" notice rather than streaming an unbounded frame.
- Text reads/writes are capped at 1 MiB; binary reads (in-app preview of images/audio/video/PDFs) at 25 MiB (bytes travel base64-encoded in a single WebSocket frame).
- Upload has no size cap - the app sends a file in 8 MiB windows over
FsUploadChunk, each acknowledged before the next, and the upload toast shows a percentage. The file grows in a hidden.clusto-upload-<uuid>.partfile next to the target and 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 one behind. Creation is exclusive (never overwrites): a name collision becomesname (1).ext. The uploaded file takes the owner of its parent directory. - Download has no size cap - it streams in 8 MiB windows over
FsReadChunkrather than fetching the whole file in one frame, so files of any size download. Unlimited streaming download applies to the native desktop and mobile apps; the web (PWA) client fetches the bytes in one frame instead, so it stays bound by the 25 MiB binary-read limit. - Download as a zip - Download on a folder, or bulk Download of a multi-selection, makes one zip instead of one save dialog per file; folders are no longer skipped, and a single file still downloads as itself. You pick the save destination first, then the node that holds the files builds the zip in a private
<data_dir>/archivesdirectory (owner-only) while a "Zipping<name>.zip..." toast shows, and the app streams it in 8 MiB windows with the usual progress toast. The name is<entry name>.zipfor one entry, or the name of the folder holding all selected entries (fileswhen they share none). Folders are added recursively with empty folders kept; symlinks below a selected folder, sockets, FIFOs and devices are skipped; same-named selections get a(2)suffix. Compressed formats (png, jpg, mp4, zip, gz, ...) are stored, everything else is deflated at a fast level, and files of 4 GiB or more use zip64. The node refuses a build that would leave less than 1 GiB free on its data directory's disk, deletes the archive once its last window is read, and sweeps an unfinished one an hour later on the next build. The web app also supports it, gathering the chunks into a Blob in the browser, so very large zips are bounded by browser memory. Session credentials are refused; the requests are admin-only. Wire messages:FsPrepareArchive { request_id, paths, node_id? }answered byArchiveReady { request_id, node_id, archive_id, total_size, file_count }orArchiveError { request_id, message }, thenReadArchiveChunk { request_id, archive_id, offset, len, node_id? }answered withFsChunk/FsChunkError. Requests forward to the owning node; a forwarded build may take up to 30 minutes. - Symlinks are reported distinctly and are not followed recursively; a delete removes the link itself, never its target.
Security
The Files view performs filesystem operations with the daemon's own privileges. Because the packaged system service runs clustod as root, the Files view grants root-level read / write / delete of any path on the selected node, with no project containment and no run-as-user restriction.
Mitigations built in:
- Defaults to the run-as user's home directory; never auto-lists
/. - Refuses to delete or move a filesystem root.
- Deletes require an explicit confirm dialog.
- The read caps above bound any single preview or edit transfer. Download and upload are exempt (they stream in bounded windows), so a large download moves a lot of bytes off the host and a large upload can fill its disk - operators should keep that in mind.
Operators who do not want this exposure should be aware that any user who can reach the daemon with a valid token can browse and modify the whole host. There is no config option to restrict it.
Wire protocol
The view is backed by an Fs* message family that mirrors the project-file family but is keyed by (node_id, absolute_path) instead of (project_id, relative_path):
| Client message | Reply | Purpose |
|---|---|---|
FsList { path?, node_id? } | FsListResult / FsError | List a directory (empty path = home) |
FsReadText { path, node_id? } | FsTextContent / FsError | Read a UTF-8 text file |
FsReadBinary { path, node_id? } | FsBinaryContent / FsError | Read a binary file for in-app preview (base64 + MIME, 25 MiB cap) |
FsReadChunk { path, offset, len, request_id, node_id? } | FsChunk / FsChunkError | Read one window of a file for streaming download (stateless ranged read, no total-size cap) |
FsWriteText { path, content, base_sha256?, node_id? } | FsSaved / FsWriteConflict / FsError | Write text with conflict detection |
FsCreateFile / FsCreateDir | FsActionResult / FsActionError | Create a file / directory |
FsMove / FsCopy / FsDelete | FsActionResult / FsActionError | Move/rename, copy, delete |
FsUploadChunk { request_id, upload_id, path, offset, data, last, node_id? } | FsActionResult / FsActionError per window | Upload one window (at most 8 MiB, base64 data) of a file to an absolute path; windows are sequential (offset equals the bytes already written, from 0) and last: true moves the hidden part file into place |
The desktop and mobile apps drive uploads through the Tauri commands fs_upload_chunk (sends one window) and upload_host_file_chunk (reads one window of a local file and returns { len, total, last }).
FsListResult carries the resolved absolute path, its parent (null at a root), a directory-first entries list, and a truncated flag. Every response echoes the serving node_id. See Protocol for the full message definitions.