git init

README.md

@@ -0,0 +1,79 @@
+# 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.