vps-control/AGENTS.md

VPS Control contributor guide

Purpose and architecture

VPS Control monitors and performs a deliberately small set of administrative actions on systemd-based Linux VPS hosts. agent/ is a Rust daemon installed on each VPS. control-plane/backend/ is the Go API and polling service, control-plane/frontend/ is the React UI, and PostgreSQL is the only durable metrics/audit store. Browsers never contact agents directly.

Security invariants

• DO NOT add arbitrary command execution.
• DO NOT expose the agent publicly by default.
• DO NOT disable authentication for convenience.
• DO NOT store plaintext credentials in source control or the database.
• DO NOT allow arbitrary systemd service names.
• DO NOT mutate unmanaged firewall rules.
• DO NOT write unbounded logs, local state, or queues.
• DO NOT add heavyweight Agent dependencies without a measured justification.
• Never pass user input to sh -c, bash -c, eval, or equivalent APIs.
• Agent subprocess arguments are separate argv values and must be validated.
• Sensitive values must be redacted from logs and audit records.

Any privileged operation requires:

1. input validation;
2. allow-listing;
3. an audit event;
4. a bounded timeout;
5. explicit error handling.

The v1 agent is unprivileged. Read-only commands are permitted by the systemd sandbox. Fail2Ban and systemd writes require narrowly scoped sudoers/polkit rules installed by an administrator; firewall mutation is intentionally disabled until the separately reviewed helper/rollback subsystem is enabled.

Repository layout

• agent/: Rust daemon, unit tests, systemd packaging.
• control-plane/backend/: Go API, auth/RBAC, polling, audit, migrations.
• control-plane/frontend/: React/Vite UI.
• docs/: architecture, security, deployment, development.
• scripts/: lifecycle script for the agent.
• examples/: safe configuration examples.

Keep module ownership narrow. JSON API fields use snake_case; URLs are under /v1 on the agent and /api/v1 on the control plane. Errors are JSON objects with an error string and an optional stable code.

Commands

# Agent
cargo fmt --manifest-path agent/Cargo.toml --check
cargo clippy --manifest-path agent/Cargo.toml --all-targets -- -D warnings
cargo test --manifest-path agent/Cargo.toml
cargo build --manifest-path agent/Cargo.toml --release

# Control-plane backend
cd control-plane/backend && gofmt -w . && go vet ./... && go test ./...

# Frontend
cd control-plane/frontend && npm ci && npm run lint && npm run typecheck
npm test -- --run && npm run build

# Deployment
docker compose -f control-plane/docker-compose.yml config
docker compose -f control-plane/docker-compose.yml build

Ordinary tests must not require root, nftables, Fail2Ban, WireGuard, or a live PostgreSQL instance. Put host-dependent tests behind explicit integration tags.

Resource and coding rules

The agent targets <=30 MiB idle RSS, a 64 MiB systemd limit, near-zero idle CPU, and negligible disk writes. Prefer /proc and /sys, collect expensive data on demand, bound request bodies/concurrency/timeouts, and do not cache history on the VPS. Production logging is info to journald and successful polls are not logged.

Rust must be formatted, clippy-clean, avoid unsafe unless documented, and keep blocking OS work out of async executor threads. Go handlers must enforce auth and RBAC before reading request bodies for mutations. React code must be typed and must not bypass the backend.

Release process

CI lints, tests, builds both Linux agent targets, emits vps-agent-linux-{amd64,arm64} plus SHA256SUMS, validates Compose, and builds containers. Release publication is a manual approval step. Update the changelog, version, checksums/signature, compatibility notes, and rollback instructions.