Admin Guide

This page covers features available only to administrators (Admin role).

User Management

ServerBee supports multiple users with two roles:

Managing Users

Go to Settings → Users:

• Create user: Enter username, password, and role
• Edit role: Change a user's role (Admin/Member)
• Delete user: Remove a user account (cannot delete the last Admin)

API Endpoints

Audit Logs

ServerBee automatically records audit logs for critical operations, helping administrators track security events.

Recorded Events

• User login (success/failure)
• Password changes
• 2FA enable/disable
• Terminal connect/disconnect
• Capability denial events

Viewing Audit Logs

Go to Settings → Audit Logs:

• Browse all audit records (paginated)
• View user, action type, details, IP address, and timestamp

API Endpoint

GET /api/audit-logs?limit=50&offset=0

Returns a paginated audit log list. Each entry contains:

{
  "id": 1,
  "user_id": "user-uuid",
  "action": "login",
  "detail": "Login successful",
  "ip": "192.168.1.100",
  "created_at": "2026-03-14T10:30:00Z"
}

Audit logs are retained for 180 days by default (configurable via retention.audit_logs_days).

Remote Commands

Administrators can dispatch commands to online servers and retrieve execution results.

Usage

1. Go to Settings → Tasks
2. Enter the command to execute
3. Select target servers (multi-select supported)
4. Click Execute

Execution Flow

1. Server creates a Task record
2. Sends the command to each target agent via WebSocket
3. Agent executes the command, reports stdout/stderr and exit_code
4. Results are stored in the task_results table

Limitations

• Command execution timeout: 300 seconds
• Requires exec capability (CAP_EXEC) on target servers
• Servers without CAP_EXEC receive a synthetic result: exit_code = -2, message: "Capability disabled"
• Only Admin role can create tasks

API Endpoints

Request body for creating a one-shot task:

{
  "command": "uptime",
  "server_ids": ["server-id-1", "server-id-2"],
  "timeout": 60
}

Scheduled Tasks

Scheduled tasks extend remote commands with cron-based execution, retries, and run history.

Creating a Scheduled Task

1. Go to Settings → Tasks.
2. Switch to the scheduled task section.
3. Enter a name, command, cron expression, target servers, timeout, retry count, and retry interval.
4. Save the task. Enabled tasks are registered with the server-side scheduler immediately.

Scheduled tasks use the server's scheduler.timezone setting when calculating next_run_at.

Fields

Execution Behavior

• Each scheduled trigger creates a run_id used to group results from all target servers and retry attempts.
• ServerBee prevents overlapping runs of the same scheduled task. If the previous run is still active, the new trigger is skipped.
• POST /api/tasks/{id}/run starts a manual run and skips retry logic.
• Disabling or deleting a task cancels its active run.
• Results include an attempt number so you can distinguish retries.

Synthetic exit codes:

API Example

{
  "task_type": "scheduled",
  "name": "Daily disk check",
  "command": "df -h",
  "server_ids": ["server-id-1"],
  "cron_expression": "0 0 8 * * *",
  "timeout": 120,
  "retry_count": 2,
  "retry_interval": 60
}

Relevant endpoints:

Billing Information

Administrators can record billing details for each server to track VPS costs and expiration dates.

Managing Billing Info

1. Go to server detail page → click Edit
2. Fill in the "Billing" section:

Expiration Alerts

Create an expiration alert rule to receive notifications before a server expires:

1. Go to Settings → Alerts
2. Create a new rule with metric type expiration
3. Set the threshold to the number of days before expiration (e.g., 7 for 7-day advance notice)
4. Link a notification group

Traffic Alerts

Use transfer_in_cycle / transfer_out_cycle / transfer_all_cycle alert types to monitor cumulative traffic within the current billing cycle. See Alerts for details.

Cost Insights

Once price and billing_cycle are filled in, ServerBee derives cost-aware signals from the recorded billing inputs and the agent's reported resources, utilization, and uptime. Insights are surfaced in three places:

• Servers list cost cell -- The /servers table shows the monthly-equivalent cost and a value grade chip per server, so cost lives next to CPU/memory/disk/traffic instead of being hidden in the edit dialog
• Dashboard server card -- Each server card shows a compact cost signal with a footnote summarizing burn rate and value grade. The signal is hidden when cost config is missing or invalid
• Per-server cost insights panel -- The server detail page renders the full breakdown: monthly-equivalent cost, billing-cycle elapsed/remaining cost and burn percent, days remaining, normalized resource unit costs (per CPU core, per GB memory, per GB disk, per TB traffic limit), and the value score with reasons and confidence

Value Score

Each configured server gets a numeric score (0-100) and a grade:

The score combines three components: per-resource unit cost percentile against peers in the same currency, utilization (idle CPU/memory and missing network/disk-IO activity contribute to idle_burn / sleeping_money), and reliability over the last 30 days (uptime ratio drives healthy_uptime / low_uptime). A confidence field (high / medium / low) reflects how much data was available, and the panel surfaces qualitative reasons such as expensive_cpu, good_memory_value, expired_billing, free_or_zero_price, or insufficient_data.

Validation

The cost insights API rejects bad billing inputs before scoring. Invalid configurations are returned with an invalid_reason of missing_price, missing_billing_cycle, invalid_billing_cycle, or invalid_price. The UI labels these rows as "invalid card cost config" rather than silently scoring zero.

API

For automation, the same data is exposed read-only at GET /api/cost/overview (fleet-wide currency totals + per-server summaries) and GET /api/servers/{id}/cost-insights (full per-server breakdown). See the API Reference for authentication details.

Agent Registration Management

Admins can manage first-time agent onboarding directly from the UI:

Discovery Key

Go to Settings to show, copy, or regenerate the auto-discovery key. Regenerating the key invalidates the previous key for future registrations, but already connected agents keep working because they use their own stored tokens.

Clean Up Unconnected Placeholders

When failed onboarding leaves behind offline New Server placeholders, the Servers page shows a Clean up unconnected action. It removes only never-initialized offline placeholders and deliberately keeps online-but-uninitialized agents.