sencho/docs/features/stack-file-explorer.mdx

---
title: Files & Volumes
description: Browse and safely edit the config files inside a stack's mounted volumes, plus the files in the stack's own directory, from the dashboard.
---

Files & Volumes gives you direct access to the files your containers actually read at runtime: the configuration inside a stack's **mounted volumes** (bind mounts and named Docker volumes), as well as the files in the stack's own source directory. A typical use is editing the Nginx and proxy configuration inside a reverse proxy's `/config` volume without leaving the dashboard. It lives on the **Files** tab inside the stack editor, alongside the dedicated `compose.yaml` and `.env` editors.

<Frame>
  <img src="/images/stack-file-explorer/overview.png" alt="Files tab open with a populated nginx configuration tree on the left and default.conf open in the editor on the right" />
</Frame>

<Note>
  Browsing is limited to the roots the stack itself declares: its source directory and the volumes mounted by its services. You cannot browse other stacks or arbitrary locations on the host.
</Note>

## Opening the Files tab

1. Click any stack in the left sidebar.
2. Click **Edit compose** in the right-hand Anatomy panel header to open the editor.
3. Switch to the **Files** tab.

The **Files** shortcut button next to **Edit compose** opens the editor with the **Files** tab already selected. The shortcut only appears when your account has **stack read** permission on the stack; without it, the tab is not offered.

Files & Volumes is available on every Sencho tier. Read actions (browse, preview, download, inspect permissions) require **stack read** permission, which every signed-in role has by default. Write actions (upload, edit, create, rename, move, change permissions, delete) require **stack edit** permission on your account.

## File roots: Volumes and stack source

The left pane opens with a **Browsing** selector that lists the roots Sencho discovered for the stack, grouped into **Volumes** and **Stack source**. When the stack declares at least one browsable volume, the explorer defaults to it; otherwise it opens on the stack source.

Each volume root is labelled by its container path (for example `/config`) and the type of mount behind it:

- **Bind mounts** map a host directory into a service (for example `./config:/config`). When the directory is reachable by Sencho, the root is fully browsable and editable.
- **Named volumes** are Docker-managed volumes. Sencho browses and edits them through a short-lived, locked-down helper container, so they work even though their on-disk location is not directly visible to the dashboard.

The same source mounted by more than one service is shown as a single root, summarised as `N mounts`. A root that any service mounts read/write is editable; a root that every service mounts read-only is browse-only.

<Note>
  Editing a config file does not restart the service that reads it. After you save, restart the relevant service so it picks up the new content.
</Note>

### When a volume cannot be browsed

A volume root shows a short explanation in place of its tree and is not browsable when:

- the bind mount points at a host path Sencho cannot reach (mount that path into the Sencho container to browse it),
- the mount targets a single file rather than a directory (a bind that maps one file straight into the container has nothing to open a tree on),
- the mount targets a protected host location: the filesystem root, kernel/OS state (`/etc`, `/proc`, `/sys`, `/dev`, `/run`, `/var/run`), the base-image binaries and libraries Sencho's own runtime depends on (`/usr`, `/bin`, `/sbin`, `/lib`, `/lib64`, `/boot`, `/root`), or the Docker socket,
- the mount overlaps an area Sencho manages at runtime: its own application directory, its data directory, the OS temp directory, or a configured upload/scanner directory (browse the owning stack's source instead), or
- a named volume cannot be resolved: either Sencho could not find it on the node that owns the stack, or it could not reach Docker to check (a transient daemon or proxy issue, distinct from the volume simply not existing).

### Named-volume editing details

Named-volume editing is best-effort and bound by file ownership. The helper container writes as an unprivileged user, so a file owned by `root` or a specific application user may not be writable; Sencho returns a clear permission error in that case. New files created in a named volume are owned by the helper user, while edits to an existing file keep that file's owner and mode. Named-volume saves are written in place and are not atomic, so a save interrupted mid-write can leave the file partially written; the files involved are small config files, which keeps the window tiny.

## Layout

The Files tab splits into two panes. The left pane holds the Browsing selector, the upload affordance, the **New file** and **New folder** buttons, and the directory tree for the selected root. The right pane is the action bar plus the file viewer.

A full-screen toggle sits next to **Close editor** whenever the Files tab is active. It collapses the identity, health, and log column on the left of the stack workspace so the tree and viewer use the full width, which helps when you are working with wide config files or a deep directory tree. Click it again (or switch to a different tab) to return to the normal two-column layout.

<Frame>
  <img src="/images/stack-file-explorer/full-screen-mode.png" alt="Files tab in full-screen mode, with the Command Center column collapsed so the tree and viewer fill the width" />
</Frame>

## Browsing the directory tree

Folders sort before files, and entries within each group sort alphabetically.

Click a folder to expand or collapse it. Click a file to open it in the viewer on the right. Symlinks render with a chain icon and behave like files when clicked. Deleting a symlink removes only the link entry; the file it points to is untouched.

The tree is fully keyboard navigable. Tab into it and use the arrow keys to move between rows: **Up** and **Down** move row to row, **Right** expands a folder (then steps into it), **Left** collapses it (or steps out to the parent), **Home** and **End** jump to the first and last visible row, and **Enter** or **Space** opens a file or toggles a folder.

Each row is fully clickable across the pane, so right-clicking anywhere on a row (not just on its name) opens that entry's context menu. Long names are never truncated: the tree scrolls horizontally so you can read the full name.

**Display cap.** Each directory render is capped at 1000 entries. A folder with more than 1000 children shows the first 1000 alphabetically with a footer noting how many entries the directory holds in total. The tree also has a filter input at the top of the list so you can narrow a large directory to the entries you care about without dropping to a shell.

## Protected files

Protection applies to the **Stack source** root. On a volume root a file named `compose.yaml` or `.env` is an ordinary config file: it opens directly in the viewer and has no delete restriction, because it is the application's own file rather than the stack's compose definition.

On the stack source root, the amber dot in the tree marks the five canonical stack files: `compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`, and `.env`.

<Frame>
  <img src="/images/stack-file-explorer/protected-tree-marker.png" alt="Stack source tree with an amber dot marker next to compose.yaml" />
</Frame>

Two behaviours follow from the marker:

- **Dedicated tab redirect.** Clicking `compose.yaml`, `compose.yml`, or `.env` jumps you to the matching **compose.yaml** or **.env** tab so the save-and-deploy controls stay in front of you. `docker-compose.yaml` and `docker-compose.yml` are still flagged as protected, but they open in the regular file viewer because they are not the canonical Sencho file.
- **Delete is blocked at the stack root.** The five canonical files at the stack root cannot be deleted through the explorer: the delete is rejected. Remove the whole stack via Stack Actions instead. A same-named file nested in a subdirectory is an ordinary file and can be deleted after the type-to-confirm step.

An override file such as `compose.override.yaml` or `docker-compose.override.yml` is not one of the five canonical names, so it carries no amber dot and no delete restriction: Sencho treats it as an ordinary file even at the stack root.

## Viewing files

When you click a text file, its contents appear in the editor on the right. The Monaco editor auto-detects the language from the extension. A **word wrap** toggle in the viewer toolbar wraps long lines instead of scrolling horizontally; it defaults on and your choice is remembered across files and sessions.

| File type | Behaviour |
|-----------|-----------|
| Text file up to 2 MB | Rendered inline with syntax highlighting. |
| Text file over 2 MB | Panel with the filename, size, and a **Download** button. |
| Binary file | Same panel layout, label is `Binary file`. |

## Editing and saving

When you have stack edit permission, the editor opens in write mode. The toolbar shows the filename and a **Save** button that activates as soon as there are unsaved changes.

When you do not, the toolbar shows a `Read-only` chip and the editor refuses input.

<Frame>
  <img src="/images/stack-file-explorer/viewer-edit-mode.png" alt="Viewer toolbar showing nginx.conf with an unsaved edit and the Save button now active" />
</Frame>

Click **Save** to write the file to disk. If you have unsaved edits and click a different file in the tree, a confirmation dialog asks whether to discard them; cancelling keeps you on the current file.

Saves use optimistic concurrency: the editor remembers when the file was last loaded, and a save that targets a stale version returns a "file changed elsewhere" notice with the current server-side content. Your typed buffer is preserved so you can review the new version and reapply your edits before saving again.

Writes to the stack source root and to bind-mount volumes are atomic at the filesystem level: Sencho stages the new content into a sibling temporary file, fsyncs, and promotes it via rename, so a crash or power loss never leaves a half-written target on disk. Named-volume writes go through the helper container instead and are not atomic; see [Named-volume editing details](#named-volume-editing-details) above.

<Warning>
  Editing a file does not restart any containers. If your stack reads the file at runtime (for example, a config file mounted as a volume), restart the relevant service after saving so the container picks up the new content.
</Warning>

## Creating files and folders

The toolbar **New file** and **New folder** buttons at the top of the tree create an entry in the currently selected directory (the parent of the file you have open, or the stack root if nothing is open). Use the toolbar buttons to create an entry directly at the stack root, where there is no folder row to right-click.

Right-click any folder for **New File** and **New Folder** entries that scope to the right-clicked folder. These write controls appear only when your account has stack edit permission.

<Frame>
  <img src="/images/stack-file-explorer/new-file-dialog.png" alt="New file modal scoped to the nginx folder, with the file name field populated and a Create button" />
</Frame>

Filenames cannot be empty, cannot contain `/` or `\`, and cannot be `.` or `..`. The Create button stays disabled until the input passes validation.

Creating a file never overwrites an existing one. If a file of that name already exists in the target directory, the dialog reports inline that the name is taken; if a folder of that name exists, Sencho rejects the creation with a message. Either way the existing entry is left untouched.

## Uploading files

The dashed **Upload file** affordance at the top of the tree opens a file picker. You can also drag and drop a file onto the dashed zone; the border lights up in the brand colour when a file is hovered over a valid drop target. Uploads are one file at a time.

| Limit | Value |
|-------|-------|
| Maximum file size | 25 MB. Uploads above the limit return a 413 error with `TOO_LARGE`. |
| Target directory | The currently selected directory, or the stack root if no file is open. |
| Same-name files | A confirmation dialog asks whether to replace the existing file. Cancelling keeps the original. |

The upload affordance is hidden for users without stack edit permission.

<Tip>
  For bulk transfers or files above 25 MB, use `scp` or `rsync` from your workstation directly to the stack directory on the host.
</Tip>

## Downloading files

When a file is selected, the right pane action bar shows **Download**. Files stream straight to your browser. Files that exceed the inline preview limit also expose a Download button inside the oversized-file panel itself.

## Renaming

Right-click any file or folder and choose **Rename**. The dialog accepts a new name following the same rules as creation. Rename keeps the entry in its current folder.

Rename appears only when your account has stack edit permission.

## Moving

Move a file or folder into a different directory in one of two ways:

- **Move to…** Right-click the entry and choose **Move to…**. The dialog shows the stack's folder tree; pick a destination folder (or **Stack root**) and choose **Move**. Destinations that would collide or make no sense (the entry's current folder, a folder inside the entry itself, or a name that is reserved at the stack root) are not selectable.
- **Drag and drop.** Drag the entry onto a folder in the tree, or onto empty space to move it to the stack root.

Moving requires stack edit permission. The protected stack files (compose / docker-compose / `.env`) at the stack root stay put: the compose CLI reads them from the stack directory, so they are not offered as move sources or root destinations. Moving a file changes only where it lives on disk; it does not redeploy or restart the stack.

## Copying and duplicating

Copy a file or folder without removing the original in one of two ways:

- **Duplicate.** Right-click the entry and choose **Duplicate** to make a copy in the same folder under an auto-suffixed name (`config.yaml` becomes `config copy.yaml`, then `config copy 2.yaml`, and so on). This is the quickest way to snapshot a file before you edit it.
- **Copy to…** Right-click the entry and choose **Copy to…** to pick a destination folder, the same way Move works. The current folder stays disabled in the picker, since a same-folder copy is what Duplicate is for.

Copying requires stack edit permission and stays within the current root. A folder is copied with its full contents, and a symlink is copied as a link rather than as the file it points to. Unlike Move, a protected stack file can be copied: duplicating `compose.yaml` to `compose.yaml.bak`, or copying it into a subfolder, is allowed because the copy is an ordinary file. Only creating a reserved name (`compose.yaml`, `.env`, and the rest) directly at the stack root is blocked.

## Working with multiple files

Select more than one entry to act on them together.

- **Select.** Hover a row to reveal its checkbox, or hold **Ctrl** (**Cmd** on macOS) and click a row to add it to the selection. Hold **Shift** and click to select a contiguous range. A plain click still opens a file in the viewer and leaves the selection untouched.
- **Act.** Once anything is selected, a bar at the top of the tree shows the count and the bulk actions.

| Bulk action | What it does |
|---|---|
| Download | Streams the whole selection as a single `.tar.gz` archive, preserving folder structure. Available to anyone who can read the stack. |
| Move | Opens the destination picker (the same one as single Move) and relocates every selected item into the chosen folder. Requires stack edit. |
| Delete | Asks for confirmation, then removes every selected item; selected folders are removed with their contents. Requires stack edit. |
| Clear | Drops the current selection. |

Bulk Move and Delete skip the protected stack files (`compose.yaml`, `.env`, and the rest) at the stack root, which are reported as kept rather than acted on; they can still be included in a Download.

Each item is processed independently. If some succeed and others fail (for example, a permission error on one file), Sencho reports how many succeeded and leaves the items that failed selected so you can see which they were and retry.

**Selection and archive limits.** A bulk action accepts at most 100 selected paths per request; select fewer items and repeat the action for a larger batch. A bulk Download is also capped at 5000 files and 1 GiB of uncompressed content: a selection that would exceed either limit is refused before the archive starts building, so narrow the selection or download large folders in smaller batches.

## Permissions (chmod)

Right-click any file and choose **Permissions** to inspect or edit its Unix mode bits. The dialog shows a 3 by 3 grid of `r` / `w` / `x` toggles for Owner, Group, and Other, plus the current octal value.

<Frame>
  <img src="/images/stack-file-explorer/permissions-dialog.png" alt="Permissions modal for a file showing the rwx grid for Owner, Group, and Other plus the current octal value" />
</Frame>

When your account has stack edit permission, the toggles are interactive and the footer adds **Save**. For viewer accounts the dialog opens read-only: the toggles render the current state and the footer shows only **Close**.

<Note>
  Permissions are applied with `chmod`. Permission changes on symlinks are not supported; edit the target file's permissions directly.
</Note>

## Deleting

There are three delete entry points. All three require stack edit permission, and all three open the same confirmation modal.

- **Toolbar delete.** With a file open in the viewer, click **Delete** in the right-pane action bar.
- **Context-menu delete.** Right-click any file or folder in the tree and choose **Delete**.
- **Non-empty folder delete.** The first attempt is non-recursive. If the folder has contents, the modal switches to `This folder is not empty. Delete everything inside?` with a destructive **Delete all** button.

When the entry is one of the five protected names, the modal asks you to type the filename before the destructive button activates.

<Frame>
  <img src="/images/stack-file-explorer/delete-protected-confirm.png" alt="Delete confirmation modal for compose.yaml requiring the user to type the filename before the destructive button activates" />
</Frame>

<Warning>
  Deletes are permanent. Sencho does not keep a trash bin or undo history for file operations.
</Warning>

## Context menu reference

<Frame>
  <img src="/images/stack-file-explorer/context-menu-folder.png" alt="Right-click menu on a folder showing New File, New Folder, Rename, Duplicate, Copy to, Move to, and Delete entries" />
</Frame>

<Frame>
  <img src="/images/stack-file-explorer/context-menu-file.png" alt="Right-click menu on a file showing Rename, Duplicate, Copy to, Move to, Permissions, and Delete entries" />
</Frame>

Right-click anywhere on a row, not only on its name, to open the menu.

| Right-click target | Admin entries (with stack edit) | Viewer entries |
|---|---|---|
| Folder | New File, New Folder, Rename, Duplicate, Copy to…, Move to…, Delete | No write entries |
| File | Rename, Duplicate, Copy to…, Move to…, Permissions, Delete | Permissions (read-only) |

**Move to…** is absent for the protected stack files (compose / docker-compose / `.env`) at the stack root, which cannot be moved out of the stack directory.

The Permissions dialog opens for everyone; only users with stack edit permission can save changes.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The Files tab is missing">
    The signed-in role lacks **stack read** permission for this stack, so the tab is not offered; opening it directly (for example via a bookmarked link) redirects you back to the Anatomy tab. Ask an admin to grant the permission on your account, or sign in with a role that already has it.
  </Accordion>
  <Accordion title="No browsable stack volumes detected">
    The stack declares no volume Sencho can reach, so the explorer opens on the stack source. This happens when the stack uses only anonymous or `tmpfs` mounts, when its bind mounts point at host paths that are not mounted into the Sencho container, or when its named volumes have not been created yet. Deploy the stack so its named volumes exist, or mount the relevant host path into the Sencho container, then reopen the tab.
  </Accordion>
  <Accordion title="A volume is shown but cannot be browsed">
    The root carries a short explanation. A bind mount to a host path Sencho cannot reach needs that path mounted into the Sencho container. A bind that targets a single file rather than a directory has no tree to browse. A mount that targets a protected host location (the filesystem root, kernel/OS paths, Sencho's own runtime binaries, or the Docker socket) or that overlaps an area Sencho manages at runtime is intentionally not browsable. A named volume that cannot be resolved on the owning node is not browsable until it exists, or until a transient Docker connectivity issue clears.
  </Accordion>
  <Accordion title="Saving a file in a named volume returns a permission error">
    Sencho writes to named volumes as an unprivileged helper user. A file owned by `root` or a specific application user may not be writable by that helper. Adjust the file's ownership or permissions on the host, or edit the file from a context that owns it, then try again.
  </Accordion>
  <Accordion title="A volume is read-only">
    Every service that mounts the volume declares it read-only (for example `./config:/config:ro`). The explorer browses it but disables the edit, upload, delete, and rename controls. Change the mount to read/write in the compose file and redeploy if you need to edit its contents from Sencho.
  </Accordion>
  <Accordion title="Cannot delete compose.yaml or .env">
    The five canonical stack files (`compose.yaml`, `compose.yml`, `docker-compose.yaml`, `docker-compose.yml`, `.env`) are protected because removing them mid-life breaks the stack. To delete a stack entirely, use **Delete stack** in the stack toolbar's overflow menu rather than removing these files individually.
  </Accordion>
  <Accordion title="Save returns 'file changed elsewhere'">
    Another writer (a teammate, a deploy hook, or an out-of-band edit on the host) saved the file after you loaded it. Use the diff to compare your edits against the current version, then save again. Your typed buffer is kept so you do not have to retype your changes.
  </Accordion>
  <Accordion title="Upload fails with no obvious reason">
    A full disk on the host backing the target directory surfaces as a generic write failure, not a dedicated error code. Check the volume mounted as `COMPOSE_DIR` (defaults to `/app/compose` inside the Sencho container) or the volume backing the target, free up space, or move it to a larger disk, then retry the upload.
  </Accordion>
  <Accordion title="File shows as 'Binary file detected' but it is a text file">
    The binary detection heuristic flagged null bytes or a high proportion of non-printable characters in the file's first kilobytes. This can happen with certain encodings, non-UTF-8 byte sequences, or unusual line-ending mixes. Click **Open as text anyway** on the binary panel to re-fetch the file as UTF-8 text and edit it in the inline viewer. Files above the 2 MB preview limit still need a Download.
  </Accordion>
  <Accordion title="Upload fails with a 413 error">
    The file exceeds the 25 MB per-file upload limit. Compress or split the file before uploading, or transfer it via `scp` or `rsync` directly to the stack directory on the host.
  </Accordion>
  <Accordion title="Cannot delete a folder">
    The first delete attempt is non-recursive. If the folder is not empty, the dialog switches to `This folder is not empty. Delete everything inside?`. Click **Delete all** to remove the folder and its contents. If the error persists, check whether a running container has an open file handle inside that directory; stop the relevant service and retry.
  </Accordion>
  <Accordion title="File saved but the container still reads the old content">
    The container caches the file at startup, or the mount is configured read-only inside the container. Restart the service after saving so the container picks up the new file.
  </Accordion>
  <Accordion title="Download button is missing">
    The Download button appears in the right-pane action bar only when a file is selected in the tree. Click any text or binary file to open it, and the button activates.
  </Accordion>
  <Accordion title="A large directory shows a 'N total entries' footer">
    Each directory render is capped at 1000 entries to keep the tree responsive. Use the filter input above the tree to narrow the list, or drop into a host shell with `cd` into the stack directory if you need to work with entries past the cap.
  </Accordion>
  <Accordion title="Write controls are missing">
    Upload, create, rename, copy, move, chmod save, and delete require **stack edit** permission. Viewer accounts can browse, preview text files, inspect permissions in read-only mode, and download (including a bulk download).
  </Accordion>
  <Accordion title="A bulk action reports that some items failed">
    Bulk delete and move process each item independently and report how many succeeded. The items that failed stay selected so you can see which they were; open one to find out why (a common cause is a permission error on a named-volume file, or a name collision at the destination), fix it, and retry on the still-selected items.
  </Accordion>
  <Accordion title="Bulk download is refused as too large">
    A bulk download is packed into a single archive capped at 5000 files and 1 GiB of uncompressed content. A selection that would exceed either limit is refused before the download starts. Narrow the selection, or download large folders in smaller batches.
  </Accordion>
  <Accordion title="A bulk action is rejected for having too many items">
    Bulk actions (download, move, delete) accept at most 100 selected paths per request. Select fewer items, or repeat the action across a few smaller batches.
  </Accordion>
</AccordionGroup>