Documentation

System Requirements

Server (Backend)

Supported Linux Distributions (Agent)

Kernel: Linux 4.15+ (recommended 5.4+ for full feature support)

Dependencies

Server Installation

mkdir -p /opt/servermind && cd /opt/servermind

cat > .env << 'EOF'
POSTGRES_PASSWORD=your_strong_password_here
EOF
chmod 600 .env

for vol in postgres_data valkey_data backend_data backend_logs jwt_secret; do
  docker volume create servermind-deploy_${vol}
done

version: "3.8"

services:
  postgres:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_DB: servermind
      POSTGRES_USER: servermind
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    ports:
      - "127.0.0.1:5433:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    shm_size: 2g
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U servermind"]
      interval: 10s
      timeout: 5s
      retries: 5

  valkey:
    image: valkey/valkey:9
    restart: unless-stopped
    command: >
      valkey-server
        --maxmemory 256mb
        --maxmemory-policy allkeys-lru
        --appendonly yes
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - valkey_data:/data

  backend:
    image: ghcr.io/exeliontech/servermind-backend:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started
    ports:
      - "443:443"       # HTTPS + QUIC + WebTransport
      - "443:443/udp"   # QUIC (UDP)
    environment:
      RUST_LOG: info,servermind=debug
      SERVERMIND_DB_MODE: external
      SERVERMIND_DB_HOST: postgres
      SERVERMIND_DB_PORT: 5432
      SERVERMIND_DB_NAME: servermind
      SERVERMIND_DB_USER: servermind
      SERVERMIND_DB_PASSWORD: ${POSTGRES_PASSWORD}
      SERVERMIND_DB_POOL_SIZE: 200
      SERVERMIND_VALKEY_MODE: external
      SERVERMIND_VALKEY_HOST: valkey
      SERVERMIND_VALKEY_PORT: 6379
    volumes:
      - backend_data:/opt/servermind/data
      - backend_logs:/opt/servermind/logs
      - jwt_secret:/etc/servermind
    healthcheck:
      test: ["CMD", "curl", "-fsk", "https://localhost:443/api/v1/health/live"]
      interval: 15s
      timeout: 5s
      start_period: 30s
      retries: 3

volumes:
  postgres_data:
    external: true
    name: servermind-deploy_postgres_data
  valkey_data:
    external: true
    name: servermind-deploy_valkey_data
  backend_data:
    external: true
    name: servermind-deploy_backend_data
  backend_logs:
    external: true
    name: servermind-deploy_backend_logs
  jwt_secret:
    external: true
    name: servermind-deploy_jwt_secret

docker compose up -d

# Check all services are healthy
docker compose ps

# Check backend health
curl -sk https://localhost/api/v1/health/live

PostgreSQL Tuning (Recommended for 100+ agents)

# /etc/postgresql/{version}/main/postgresql.conf (Ubuntu/Debian)
# /var/lib/pgsql/data/postgresql.conf (RHEL/Rocky)
max_connections = 300
shared_buffers = 2GB
effective_cache_size = 6GB
work_mem = 32MB
maintenance_work_mem = 512MB
max_wal_size = 4GB
checkpoint_completion_target = 0.9
random_page_cost = 1.1
effective_io_concurrency = 200
log_min_duration_statement = 1000

Agent Installation

Getting the Activation Token

Quick Install (One-Liner)

curl -fsSL https://get.servermind.io | sudo bash -s -- \
  --server-url https://your-server.com \
  --token sm_your_activation_token

Install via Package Repository

Ubuntu/Debian:

curl -fsSL https://packages.servermind.io/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/servermind.gpg
echo "deb [signed-by=/usr/share/keyrings/servermind.gpg] https://packages.servermind.io/apt stable main" | sudo tee /etc/apt/sources.list.d/servermind.list
sudo apt update && sudo apt install servermind-agent

RHEL/Rocky/Alma:

# If repo not already added (see Server Installation)
sudo dnf install servermind-agent

Then configure and start:

sudo servermind-agent configure --server-url https://your-server.com --token sm_your_token
sudo systemctl enable --now servermind-agent

Manual Install (Binary)

Step 1 — Download:

curl -fsSL https://releases.servermind.io/latest/servermind-agent -o /usr/bin/servermind-agent
chmod +x /usr/bin/servermind-agent

Step 2 — Configure:

# Interactive setup
sudo servermind-agent configure --interactive

# Or non-interactive
sudo servermind-agent configure \
  --server-url https://your-server.com \
  --token sm_your_activation_token \
  --agent-id agent-$(hostname)

Step 3 — Install systemd service:

# /etc/systemd/system/servermind-agent.service
[Unit]
Description=ServerMind Monitoring Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
ExecStart=/usr/bin/servermind-agent
Restart=on-failure
RestartSec=10
TimeoutStopSec=15

MemoryMax=1G
MemoryHigh=768M
TasksMax=512

Environment="RUST_LOG=info"
WorkingDirectory=/var/lib/servermind

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now servermind-agent

Step 4 — Verify:

sudo systemctl status servermind-agent
sudo journalctl -u servermind-agent -f

Agent Configuration

The agent stores its configuration in an encrypted identity database:

Agent Parameters

Split Agent Mode (Production)

For security isolation, the agent can run as 4 specialized processes:

# Create services
sudo systemctl enable --now servermind-collector  # QUIC connection, IPC server
sudo systemctl enable --now servermind-monitor    # Read-only monitoring
sudo systemctl enable --now servermind-control    # Mutations, PTY terminal
sudo systemctl enable --now servermind-platform   # Kubernetes, Docker

Each process uses --mode=collector|monitor|control|platform.

Network Requirements

Outbound (Agent → Server)

Inbound (Server)

Firewall Rules

# Server — allow inbound
sudo ufw allow 443/tcp   # HTTPS + WebSocket + WebTransport
sudo ufw allow 443/udp   # QUIC

# Agent — only outbound needed (usually allowed by default)
# No inbound rules required

Proxy / NAT Support

• Agents work behind NAT (outbound-only connections)
• QUIC handles network switching with 0-RTT reconnection
• WebSocket fallback works through HTTP proxies
• For corporate proxies: set HTTPS_PROXY environment variable

Transport Priority

SSL/TLS Configuration

Self-Signed (Development)

The backend auto-generates a self-signed certificate on first startup. Access via https://your-ip and accept the browser warning.

For agents:

servermind-agent configure --server-url https://your-server --token sm_... --tls-skip-verify

Let's Encrypt (Production)

Custom Certificate

Upload via Admin > Settings > TLS (PEM format — certificate + private key), or use environment variables:

SERVERMIND_TLS_CERT=/path/to/cert.pem
SERVERMIND_TLS_KEY=/path/to/key.pem

Architecture

Browser ──WebTransport──► Backend (port 443) ──QUIC──► Agent
                              │                          │
                              ├── PostgreSQL 18           ├── Collector (QUIC + IPC)
                              ├── Valkey 9                ├── Monitor (read-only)
                              └── Static Files            ├── Control (PTY + write)
                                  (embedded in binary)    └── Platform (K8s + Docker)

• Protocol: QUIC primary, WebSocket fallback — automatic negotiation
• Self-contained binaries with no runtime dependencies
• All communication encrypted with TLS 1.3

Troubleshooting

Agent won't connect

# Check agent status
sudo systemctl status servermind-agent
sudo journalctl -u servermind-agent --since "5 min ago"

# Test connectivity
curl -sk https://your-server/api/v1/health/live

# Test QUIC (UDP 443)
nc -zuv your-server 443

Database issues

# Check PostgreSQL
sudo -u postgres psql -d servermind -c "SELECT 1;"

# Check Valkey
valkey-cli ping

High memory usage

# Agent memory limit (systemd)
MemoryMax=1G
MemoryHigh=768M

# Split agent mode reduces per-process memory
sudo systemctl enable servermind-collector servermind-monitor servermind-control

Upgrade

Agent

curl -fsSL https://releases.servermind.io/latest/servermind-agent -o /usr/bin/servermind-agent.new
mv /usr/bin/servermind-agent.new /usr/bin/servermind-agent
chmod +x /usr/bin/servermind-agent
sudo systemctl restart servermind-agent

Backend (Docker)

docker compose pull
docker compose up -d

Backend (Binary)

curl -fsSL https://releases.servermind.io/latest/servermind-backend -o /opt/servermind/servermind-backend.new
mv /opt/servermind/servermind-backend.new /opt/servermind/servermind-backend
chmod +x /opt/servermind/servermind-backend
sudo systemctl restart servermind