Documentation

How It Works

You run the ServerMind server on your own infrastructure. It serves the web console and accepts agent connections on port 443. Each Linux machine you manage runs the ServerMind agent, which connects out to your server — agents never need inbound ports.

Browser ──HTTPS / WebTransport──► ServerMind server (:443) ◄──QUIC── Agent
                                     │                                │
                                     ├── PostgreSQL                   ├── servermind-agent-collector
                                     ├── Valkey                       ├── servermind-agent-monitor
                                     └── Web console (built in)       └── servermind-agent-control

The free tier covers 1 server. See pricing for paid plans.

Requirements

Server

• A Linux host with Docker Engine and the Docker Compose plugin (docker compose).
• Port 443 reachable from your browsers and agents, on both TCP and UDP.
• Outbound HTTPS to license.servermind.io (activation) and packages.servermind.io (agent releases).

Agent (managed machines)

Releases below the glibc floor, such as CentOS 7/8, Ubuntu 18.04 or Amazon Linux 2, are not supported.

Install the Server

The server runs with Docker Compose: the ServerMind server image (packages.servermind.io/servermind-server:latest) plus its database (PostgreSQL) and cache (Valkey), which the compose file runs for you. The compose file and image are published on packages.servermind.io — free to download, no account or key needed. You activate the server afterwards with a code from the customer portal.

Step 1 — Download the compose file

mkdir servermind && cd servermind
curl -fsSLO https://packages.servermind.io/server/docker-compose.yml

Step 2 — Set the database password

The compose file refuses to start without POSTGRES_PASSWORD. Put it in a .env file next to it:

echo "POSTGRES_PASSWORD=$(openssl rand -hex 24)" > .env
chmod 600 .env

Step 3 — Start

docker compose up -d

Step 4 — Verify

docker compose ps
curl -sk https://localhost/api/v1/health/live

What the compose file sets up:

Activation & First Login

Add Servers (Agents)

Agents are installed from your own ServerMind server. The console builds the exact command for you, including a one-time registration token and your server's certificate fingerprint.

Get the install command

The command looks like this:

curl -fsSL -k https://<your-server>/install.sh | sudo bash -s -- \
  --token sm_<registration-token> \
  --cert-fingerprint <sha256-fingerprint>

Installer options

What gets installed

The installer downloads the agent package from https://<your-server>/packages/, installs it, enrolls with your server and starts three systemd services:

systemctl status servermind-agent-collector servermind-agent-monitor servermind-agent-control
sudo journalctl -u servermind-agent-collector -f

Network

• Agents only make outbound connections; no inbound ports need to be opened on managed machines.
• QUIC over UDP 443 is the primary agent transport. If QUIC cannot connect, the agent falls back to WebSocket over TCP 443 and keeps retrying QUIC in the background.
• The server itself connects out to license.servermind.io (activation and license check-ins) and packages.servermind.io (new agent releases).

# Example: open the server ports with ufw
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

TLS Certificates

On first start the server generates a self-signed certificate automatically. It covers localhost and every address the server detects it can be reached on (LAN, VPN, public), so agents can connect by IP. Browsers show a warning for self-signed certificates that you accept once.

Agents don't rely on a certificate authority: the install command carries the certificate's SHA-256 fingerprint, and the agent pins it. This is why you should always use the command generated by Install Agent rather than --insecure.

Upgrade

Server

docker compose pull && docker compose up -d

Agents

Agents are upgraded from the console, not by hand: open Fleet → Agent Updates, select the agents and start the update. Each agent verifies the package signature, installs it, checks its own health and rolls back automatically if the new version fails. Agents that are offline are updated when they reconnect.

Your server checks packages.servermind.io for new agent releases every 6 hours and accepts only releases with a valid ServerMind signature; agents download updates from your server, never from the internet.

Troubleshooting

Server

docker compose ps
docker compose logs -f backend
curl -sk https://localhost/api/v1/health/live

Agent doesn't appear in the console

• From the agent machine, check the server is reachable: curl -sk https://<your-server>/api/v1/health/live. If it isn't, fix the firewall or use a different address in Backend address agents connect to.
• Check the services and logs: systemctl status servermind-agent-collector servermind-agent-monitor servermind-agent-control and journalctl -u servermind-agent-collector.
• Restart: sudo systemctl restart servermind-agent-collector servermind-agent-monitor servermind-agent-control.
• To re-enroll, generate a fresh command in Install Agent and run it again.

Installer errors