---
url: https://clusto.app/docs/files-view.md
description: Browse and manage the whole filesystem of any Clusto cluster node.
---

# 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](/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, `showSaveFilePicker` on 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 system `clustod` does 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](/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>.part` file 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 becomes
  `name (1).ext`. The uploaded file takes the owner of its parent directory.
* **Download has no size cap** - it streams in 8 MiB windows over `FsReadChunk`
  rather 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>/archives` directory (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>.zip` for one entry, or the name
  of the folder holding all selected entries (`files` when 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 by `ArchiveReady { request_id, node_id, archive_id, total_size,
  file_count }` or `ArchiveError { request_id, message }`, then
  `ReadArchiveChunk { request_id, archive_id, offset, len, node_id? }` answered
  with `FsChunk` / `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](/protocol) for the full message
definitions.
