# File Manager

> Browse, read, edit, upload, download, and manage remote files through ServerBee.

URL: https://docs.serverbee.app/en/docs/file-manager

File Manager provides controlled remote filesystem access through the ServerBee agent. It is meant for operational tasks such as checking logs, editing small configuration files, and transferring files without opening a full terminal.

File Manager is available only to Admin users. This includes browsing, stat, reading, downloading, and transfer management as well as operations that modify files.

<Callout type="warn">
  File Manager is a high-risk feature. Enable it only on trusted servers, and restrict `root_paths` to the minimum directories needed.
</Callout>

## Requirements [#requirements]

File Manager must be enabled at two layers, **both on the agent host** — capabilities are agent-owned, so the server cannot turn them on:

1. **`file` capability** -- the `file` capability is off by default. Add it to the agent's `[capabilities]` allow list (or pass `--allow-cap file`). See [Capabilities](/en/docs/capabilities).
2. **File subsystem policy** -- set `[file].enabled = true` and configure at least one allowed root path.

Both layers must be satisfied before the agent advertises the capability: if `file` is allowed but the subsystem is disabled (or `root_paths` is empty), the agent drops `file` from its reported capabilities at startup, so the server and UI never show a File Manager that cannot serve requests.

Example `agent.toml`:

```toml
[capabilities]
# Turn on the high-risk file capability for this host.
allow = ["file"]

[file]
enabled = true
root_paths = ["/home", "/var/log", "/etc/serverbee"]
max_file_size = 1073741824
# Defaults shown here for clarity
deny_patterns = ["*.key", "*.pem", "id_rsa*", ".env*", "shadow", "passwd"]
```

Equivalent environment variables:

```bash
SERVERBEE_CAPABILITIES__ALLOW=["file"]
SERVERBEE_FILE__ENABLED=true
SERVERBEE_FILE__ROOT_PATHS=/home,/var/log,/etc/serverbee
SERVERBEE_FILE__MAX_FILE_SIZE=1073741824
```

Restart the agent after editing the config for the capability change to take effect.

## Accessing the File Manager [#accessing-the-file-manager]

Open a server's action menu and click **Files**, or navigate directly to:

```
/files/{serverId}
```

The button is hidden when `CAP_FILE` is not in the server's effective capabilities.

## Permissions [#permissions]

Only Admin users can use File Manager. Every file API endpoint is behind the Admin authorization check because even read operations can expose sensitive files from a managed host.

All high-risk file operations are recorded in the audit log, including attempts denied because the capability is disabled.

## Supported Operations [#supported-operations]

| Operation      | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| List directory | Browse files and directories below allowed roots                        |
| Stat           | Load metadata for one path                                              |
| Read           | Read UTF-8 text content for preview/editor use                          |
| Write          | Replace file content with provided text                                 |
| Upload         | Upload a local file to a remote path                                    |
| Download       | Start a server-mediated download transfer, then fetch it from ServerBee |
| Delete         | Delete a file or recursively delete a directory                         |
| Mkdir          | Create a directory                                                      |
| Move           | Rename or move a file/directory                                         |
| Transfers      | View and cancel active file transfers                                   |

## Security Model [#security-model]

The agent enforces path safety before touching the filesystem:

* `root_paths` is an allow-list; an empty list rejects all file operations.
* Every path must resolve inside one of the configured roots.
* `deny_patterns` blocks sensitive names such as private keys, `.env*`, `shadow`, and `passwd`.
* The agent also checks its local capabilities, so a server-side change cannot override an agent-local deny.
* The server checks `CAP_FILE` before dispatching any file message to the agent.

## Limits [#limits]

| Limit                             | Default | Where configured                                                      |
| --------------------------------- | ------- | --------------------------------------------------------------------- |
| Upload size                       | 100 MB  | Server `file.max_upload_size` / `SERVERBEE_FILE__MAX_UPLOAD_SIZE`     |
| Agent read/download max file size | 1 GB    | Agent `[file].max_file_size` / `SERVERBEE_FILE__MAX_FILE_SIZE`        |
| Inline read chunk                 | 384 KB  | Protocol limit to keep WebSocket frames below the configured max size |

Uploads and downloads are chunked. A download creates a temporary transfer on the server that can be cancelled while pending or in progress.

## API [#api]

All File Manager endpoints require Admin, including list, stat, read, download, and transfer endpoints.

| Method | Path                                 | Description                                         |
| ------ | ------------------------------------ | --------------------------------------------------- |
| POST   | `/api/files/{server_id}/list`        | List a directory; body `{ "path": "/var/log" }`     |
| POST   | `/api/files/{server_id}/stat`        | Stat a path                                         |
| POST   | `/api/files/{server_id}/read`        | Read UTF-8 text content                             |
| GET    | `/api/files/download/{transfer_id}`  | Download a ready transfer owned by the current user |
| GET    | `/api/files/transfers`               | List transfers owned by the current user            |
| POST   | `/api/files/{server_id}/write`       | Replace file content                                |
| POST   | `/api/files/{server_id}/delete`      | Delete file/directory; supports `recursive`         |
| POST   | `/api/files/{server_id}/mkdir`       | Create a directory                                  |
| POST   | `/api/files/{server_id}/move`        | Move or rename a path                               |
| POST   | `/api/files/{server_id}/download`    | Start a download transfer                           |
| POST   | `/api/files/{server_id}/upload`      | Upload multipart form with `path` and `file` fields |
| DELETE | `/api/files/transfers/{transfer_id}` | Cancel a transfer                                   |

Examples:

```bash
curl -X POST https://your-server/api/files/server-id/list \
  -H "X-API-Key: serverbee_..." \
  -H "Content-Type: application/json" \
  -d '{"path":"/var/log"}'
```

```bash
curl -X POST https://your-server/api/files/server-id/upload \
  -H "X-API-Key: serverbee_..." \
  -F 'path=/tmp/example.txt' \
  -F 'file=@example.txt'
```

<Cards>
  <Card title="Agent Setup" href="/en/docs/agent" />

  <Card title="Configuration" href="/en/docs/configuration" />

  <Card title="Capabilities" href="/en/docs/capabilities" />
</Cards>