Clusev Documentation

Clusev is a self-hosted control plane for a fleet of Linux servers — one security-first dashboard that administers your machines directly over SSH. It installs nothing on the servers you manage and never re-implements their daemons; it orchestrates the real ones.

How it works

You run one Docker stack on one VM — the panel host. The browser talks to it over HTTPS and a WebSocket for live telemetry. Clusev reaches each of your servers over SSH exec + SFTP (via phpseclib), using credentials sealed in an encrypted vault that never leaves the control plane.

Two kinds of machine

Keep these straight — they have very different requirements:

• The panel host — the single VM that runs Clusev (the Docker stack). You install here. See requirements.
• The servers you manage — everything else in your fleet. They need nothing installed — just SSH reachable from the panel.

Server requirements

What you need before installing: one small VM for the panel, and SSH access to the servers you want to manage.

The panel host

A single VM that runs the whole Docker stack (app, MariaDB, Redis, Reverb, queue). Modest — a €4/month VPS is plenty for a small fleet.

The only tool you need pre-installed is git to fetch the repo — the installer sets up Docker and everything else. Minimal cloud images often ship without git; the install command shows how to add it.

The servers you manage

These need nothing installed. Clusev is agentless — how much it can do depends only on what the target already runs:

• Metrics (CPU, memory, disk, load) work on essentially any Linux with a standard /proc.
• Service control (start / stop / restart / journal) needs systemd.
• Hardening (firewall + fail2ban + auto-updates) needs the host's firewall (ufw / firewalld) and one of apt / dnf / zypper.

The one hard requirement is SSH reachable from the panel host. See the full matrix under Supported systems.

Installation

One command. The installer is idempotent — safe to re-run — and sets up Docker, all secrets, the database and the first admin in a single pass.

# minimal images often lack git
sudo apt-get update && apt-get install -y git
git clone https://github.com/clusev/clusev.git
cd clusev
sudo ./install.sh

What the installer does

1. Installs Docker

   On Debian/Ubuntu, from Docker's official repository — if it isn't already present.

2. Creates a clusev system user

   A dedicated, unprivileged user in the docker group that owns and runs the stack — with its own random password.

3. Asks only two things

   The HTTP port (default 80) and an admin e-mail (default admin@clusev.local). No domain is asked for — you set that later in the dashboard. Preset CLUSEV_ADMIN_EMAIL / CLUSEV_DOMAIN in the environment for a fully unattended install.

4. Builds and starts everything

   Generates all secrets once (never regenerated on re-run), builds the image, starts the stack, runs migrations, and creates the first administrator with a random one-time password.

5. Prints a one-time summary

   The dashboard URL, your admin login + one-time password, and the clusev host user + its password. Both passwords are shown only once — note them down.

First login

Open the dashboard URL from the summary and sign in with your admin e-mail and the one-time password.

Set your own password

Setting your own password is recommended — a banner keeps reminding you until you do — but no longer forced, so a missed reminder can never lock you out of your own panel. Change it (and the login e-mail) any time under Settings → Profile.

Enable 2FA (optional)

Two-factor auth is optional but recommended. From Settings → Security you can enable a TOTP app and/or a hardware security key, and generate one-time backup codes. See 2FA, audit & sessions.

The guided tour

On first login a short guided tour highlights the key areas — the fleet switcher, dashboard, terminal and settings. Replay it any time from Settings.

Language — German & English

The interface ships in German (default) and English — every screen, label and message is fully translated. Switch language any time under Settings → Profile; only native technical tokens (nginx.service, SSH, 2FA) stay untranslated.

Adding servers

Add a machine by giving Clusev an address and SSH credentials. Nothing is installed on the target — the first connection just works.

SSH credentials & the vault

Authenticate with an SSH private key (recommended) or a password. Whatever you enter is encrypted at rest in the credential vault and only ever decrypted inside the control plane to open a connection — it never reaches the browser and never leaves the panel host.

The fleet switcher

Once added, every page — dashboard, services, files, terminal — is scoped to the currently selected server. Switch across your whole fleet from the switcher at the top of the app. Adding servers is always free and never limited.

Dashboard & metrics

Live CPU, memory, load and disk per server, streamed in real time over a private WebSocket channel.

The dashboard reads metrics from the target's /proc over SSH and broadcasts them to your browser over an authenticated Reverb channel — the whole fleet, at a glance, updating live. The Server details page adds identity, resource gauges, specs, volumes, network interfaces and SSH keys for a single host.

Services & files

systemd services

List units, start / stop / restart them, and tail the live journal — per service, per server, without leaving the panel. Requires systemd on the target; where it's absent, service control is shown as unavailable rather than failing silently.

SFTP file manager

Browse the remote filesystem over SFTP, edit text files in place, preview images, and upload / download. Same encrypted SSH session as everything else — no extra daemon on the target.

Web terminal

A full SSH terminal in the browser — one per server, plus one for the Clusev host itself.

The terminal is a real PTY with tab-completion and window-resize handling, bridged from the browser to SSH by a small sidecar. On first connect the server's host key is pinned; if it ever changes, Clusev fails the connection closed rather than silently trusting a possible man-in-the-middle. There's also a terminal for the Clusev host itself, so you can manage the panel VM without a separate SSH client.

2FA, audit & sessions

Pluggable two-factor auth, a tamper-evident audit log, and per-device session control.

Two-factor authentication

Enable TOTP (any authenticator app) and/or a hardware security key from Settings → Security, or leave 2FA off — it's optional but recommended. Generate one-time backup codes and store them safely; they're your fallback if you lose your device.

Audit log

Every action is recorded in a complete, searchable, tamper-evident audit log and attributed to the administrator who performed it.

Administrators & sessions

Add further admin accounts under Settings. View active sessions per device and revoke them individually, per user, or globally. SSH credentials for your fleet stay sealed in the encrypted vault throughout.

Firewall & hardening

One-click firewall and fail2ban controls, plus a guided flow to lock down SSH without locking yourself out.

• Firewall — view and edit ufw / firewalld rules per server from the Server details page.
• fail2ban — see jail status and toggle protection with one click.
• SSH key flow — a guided “generate an SSH key and disable password login, safely” sequence that verifies key access before it turns passwords off, so a misconfiguration can't strand you.
• Automatic updates — enable unattended security upgrades where the package manager supports it.

WireGuard

Stand up a WireGuard tunnel straight from the dashboard, manage peers and live status — and optionally gate the panel to the tunnel only.

1. First-time setup

   Create the WireGuard interface from the dashboard — the host gate provisions the server keys and config for you.

2. Add peers

   Generate peer configs (with QR for mobile), see live handshake status and per-peer traffic history, and remove peers when they're done.

3. Gate the panel (optional)

   Restrict access to Clusev — and even SSH — to the tunnel only, so the dashboard isn't exposed on the public internet at all.

Domain & TLS

Run on a bare IP over HTTP, add a domain for automatic HTTPS, or sit behind your own reverse proxy — switch modes any time in the dashboard.

Bare IP (no domain)

Served over plain HTTP at http://<server-ip>. This address always stays reachable as a recovery path, even after you configure a domain.

With a domain

Set it under System → Domain & TLS at any time (or preset CLUSEV_DOMAIN at install). The panel obtains and renews a Let's Encrypt certificate automatically and serves HTTPS — just point DNS at the server. Let's Encrypt needs publicly reachable ports 80/443.

Behind your own reverse proxy

If a proxy already terminates TLS, switch TLS-Terminierung to Externer Reverse-Proxy. The panel then serves HTTP only and trusts the proxy's forwarded scheme — set TRUSTED_PROXY_CIDR to the proxy's address and firewall the HTTP port so only the proxy can reach it.

Updating

One command pulls the latest code, then rebuilds, restarts and migrates — preserving your secrets, domain and e-mail settings.

sudo clusev update   # pull → rebuild → restart → migrate

sudo clusev update fast-forwards the repo (it never discards local changes), re-runs the idempotent installer non-interactively, and updates itself if the script changed. The older two-step git pull && sudo ./install.sh still works.

Recovery

Locked out? There's always a way back in — self-service first, host command as a last resort.

Self-service reset

The forgot-password screen offers an e-mail reset link (valid 15 minutes) when SMTP is configured, or an inline 2FA-proof reset — e-mail + a TOTP code or backup code + a new password — as a fallback.

Completely locked out

Lost your password and 2FA, with no SMTP? Recover from the panel host:

clusev reset-admin

This clears the second factor so you can set a new password on next login. The bare-IP http://<server-ip> address is always available too, if a domain becomes unreachable.

Supported systems

Clusev manages whatever it can reach over SSH. How much works depends on the target's init system and package manager.

Metrics read from /proc and work on essentially any Linux. Service control needs systemd. Hardening uses the host's firewall (ufw / firewalld) and package manager (apt / dnf / zypper); where those aren't present, the action is shown as unavailable rather than failing.

FAQ

Do I install anything on the servers I manage?

No. Clusev is agentless — it connects over SSH (exec + SFTP). The only machine that runs software is the panel host.

Is multi-server management really free?

Yes — fleet management is never paywalled. Clusev is open core under AGPL-3.0. Optional Pro modules (SSO/LDAP, RBAC, audit export, alerting) are separate add-ons.

Where are my SSH credentials stored?

Encrypted at rest in a vault on the panel host. They're decrypted only inside the control plane to open a connection and are never sent to the browser.

Where does my data live?

Entirely on your VM. Clusev is self-hosted — your servers, your database, your keys. Nothing phones home.