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.

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.
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:

[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:

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

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

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

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

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

API

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

Examples:

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"}'

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'