# 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.

```text
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:

```bash
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:

```bash
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:

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

See [deployment](docs/deployment.md), [security](docs/security.md), and the
[agent](agent/README.md) and [control-plane](control-plane/README.md) manuals.

## Repository

```text
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](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](docs/development.md). CI-compatible commands are also
listed in [AGENTS.md](AGENTS.md). This repository is licensed under Apache-2.0.