vps-control/README.md

VPS Control

Production-oriented monitoring and constrained management for Debian and Ubuntu VPS hosts. A small Rust daemon exposes semantic system APIs over a private WireGuard or TLS network. A separately hosted Go + React control plane provides inventory, history, RBAC, and an immutable audit trail.

Browser ──HTTPS──> React/nginx ──> Go API ──private network──> Rust agent
                                      │
                                  PostgreSQL
                                      ▲
                         Grafana (Prometheus/Loki APIs)

The project intentionally has no remote shell. The agent defaults to 127.0.0.1:9105, reads credentials from root-managed files, runs as an unprivileged system user, and is bounded by systemd resource controls.

Quick start

Control plane:

cp control-plane/.env.example control-plane/.env
# Fill all CHANGE_ME values and create the secret files documented below.
docker compose -f control-plane/docker-compose.yml up -d --build

Agent development build:

cargo build --manifest-path agent/Cargo.toml --release
sudo install -m 0755 agent/target/release/vps-agent /usr/local/bin/vps-agent
sudo install -m 0640 examples/agent-config.toml /etc/vps-agent/config.toml

For a release installation, download the lifecycle script and checksum as separate files, verify with sha256sum -c, then run:

sudo ./scripts/vps-agentctl.sh install --version v0.1.0

See deployment, security, and the agent and control-plane manuals.

Repository

agent/                 Rust VPS daemon and systemd packaging
control-plane/backend/ Go API, PostgreSQL persistence, auth/RBAC/audit
control-plane/frontend React/Vite dashboard
docs/                  architecture, threat model, operations, development
scripts/               safe agent lifecycle utility
examples/              deployable configuration examples

Security and compatibility

Supported targets are Debian 12+, Ubuntu 22.04, and Ubuntu 24.04 with systemd. Keep the agent behind WireGuard or localhost/reverse tunnel. Never bind it to a public address without TLS, host firewall policy, and an explicit risk review. Read docs/security.md before enabling write operations.

The current v1 scope supports read-only system, network, socket, firewall, Fail2Ban, WireGuard, and allow-listed service inspection; manual Fail2Ban ban/unban and service restart are audited. Managed firewall transactions and L7 rate-limit configuration are deliberately deferred until a separately privileged helper can guarantee crash-safe rollback.

Optional observability endpoints make the backend a constrained Prometheus-compatible metrics source and Loki-compatible log source for Grafana. Grafana never receives an agent address or agent credential.

Development

See docs/development.md. CI-compatible commands are also listed in AGENTS.md. This repository is licensed under Apache-2.0.