---
url: https://clusto.app/docs/file-explorer.md
description: >-
  Browse project and parent directories in the sidebar, manage project files,
  and attach clipboard, dropped, device, camera or cross-node files to terminal
  prompts.
---

# 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](/chats#files-for-a-chat) and for
[SSH sessions](/ssh-view#files-for-an-ssh-session); see
[Panels per view](#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](#panels-per-view). The
[Git panel](/git-panel) and [Run panel](/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](/cluster-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](/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](/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](/chats#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
  `showSaveFilePicker` on 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.

1. You pick the save destination first.
2. The node that holds the files builds the zip in a private
   `<data_dir>/archives` directory (mode 0700, owner-only ACL on Windows). A toast
   reads "Zipping `<name>.zip`..." while it builds.
3. 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](#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](/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](/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 `.git` directory 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 `chown`ed 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.
