ServerBee Docs

Control which features each agent is allowed to use with per-server capability toggles.

ServerBee supports per-agent capability toggles that let administrators control exactly which operations each server is allowed to perform, enforcing the principle of least privilege.

Capability List

ServerBee defines 8 capability bits, divided into two risk levels:

High Risk (Disabled by Default)

Capability	Bit Value	Description
Web Terminal	`CAP_TERMINAL` (1)	Allow opening a remote terminal via browser
Remote Exec	`CAP_EXEC` (2)	Allow remote command execution
File Manager	`CAP_FILE` (64)	Allow remote file browsing, editing, upload/download
Docker Management	`CAP_DOCKER` (128)	Allow Docker container monitoring, log streaming, and container actions

These capabilities involve executing arbitrary code or accessing the filesystem on the target server. They are disabled by default. Only enable them on trusted servers.

File Manager requires additional agent-side configuration (root_paths, deny_patterns) for path sandbox security. See the Agent Setup and Configuration pages for details.

Low Risk (Enabled by Default)

Capability	Bit Value	Description
Auto Upgrade	`CAP_UPGRADE` (4)	Allow remote binary upgrades
ICMP Ping	`CAP_PING_ICMP` (8)	Allow ICMP probe tasks
TCP Probe	`CAP_PING_TCP` (16)	Allow TCP port probe tasks
HTTP Probe	`CAP_PING_HTTP` (32)	Allow HTTP probe tasks

Newly registered agents default to a capabilities value of 60 (auto upgrade plus all three ping capabilities enabled).

Configuration

Single Server

Go to Dashboard → click a server → server detail page
In the Capabilities section, use toggle switches to enable or disable features
Changes take effect immediately — the server pushes a CapabilitiesSync message to the agent via WebSocket

Batch Configuration

Go to Settings → Capabilities
Search or multi-select servers
Enable or disable specific capabilities in bulk
Click save to update all selected servers at once

API Configuration

Update a single server (via PUT /api/servers/{id}):

curl -X PUT https://your-server/api/servers/{id} \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{"capabilities": 63}'

Batch update:

curl -X PUT https://your-server/api/servers/batch-capabilities \
  -H "Cookie: session=..." \
  -H "Content-Type: application/json" \
  -d '{"server_ids": ["id1", "id2"], "capabilities": 63}'

The capabilities value is a bitwise OR of individual capability bits. Examples:

60 = Auto Upgrade + ICMP + TCP + HTTP (default)
255 = all capabilities enabled
188 = Auto Upgrade + ICMP + TCP + HTTP + Docker
124 = Auto Upgrade + ICMP + TCP + HTTP + File Manager
0 = all capabilities disabled

Defense in Depth

ServerBee validates capabilities on both the server side and agent side:

Server-Side Enforcement

Terminal: WebSocket upgrade rejected with 403
Exec: POST /api/tasks and scheduled task runs filter out disabled servers and write synthetic results (exit_code = -2, message: "Capability 'exec' is disabled")
Auto Upgrade: POST /api/servers/{id}/upgrade returns 403 when CAP_UPGRADE is disabled
Ping and Traceroute: Probe tasks are filtered by capability; traceroute requires effective CAP_PING_ICMP
File Manager: file endpoints reject requests before dispatch when CAP_FILE is disabled
Docker: Docker read/action endpoints and Docker log WebSocket routes require CAP_DOCKER and agent runtime Docker support

Agent-Side Enforcement

Even if a server-side message is bypassed, the agent checks capabilities locally:

Returns a CapabilityDenied message for unauthorized commands
The server writes a synthetic result (exit_code = -1) upon receiving CapabilityDenied
Denial events are recorded in the audit log

Real-Time Sync

When an administrator changes capabilities:

Server sends CapabilitiesSync to the target agent via WebSocket
Agent atomically updates its local capabilities value using AtomicU32
Server sends CapabilitiesChanged to all connected browsers via WebSocket
Frontend updates the UI state in real time
If ping-related capability bits change, the server automatically re-syncs ping tasks

Frontend Behavior

Server Detail page: Capabilities toggle section — online servers can be toggled in real time
Settings → Capabilities: Batch management page with search and multi-select
Tasks page: Servers without CAP_EXEC are greyed out, results marked as "skipped"
Terminal button: Hidden for servers without CAP_TERMINAL
Files button: Hidden for servers without CAP_FILE; clicking opens the file manager at /files/{serverId}
Docker link: Hidden for servers without CAP_DOCKER; clicking navigates to /servers/{serverId}/docker

Server Config vs Client Lock

Runtime capability state now has three layers:

capabilities: the server-configured bitmap stored in the database
agent_local_capabilities: the bitmap allowed by the running agent process
effective_capabilities: the runtime intersection actually enforced by the system

When an agent locally disables a capability, the UI shows the toggle as disabled with the tooltip 客户端关闭. This means the running agent has locked that capability off locally, and the server cannot turn it back on until the agent is restarted with a different local policy.

Capabilities