Stack-agnostic METHOD for an invoked AI agent to govern a self-hosted VPS with a contained blast radius. Governs HOW the agent operates the VPS — the concrete stack (Coolify config, Docker commands, dump scripts) lives in the consumer VPS repo, never here.
Triggers: govern the VPS, administer the server, deploy to the server, GitOps deploy, provision Coolify, backup a self-hosted DB, restore a backup, monitor the VPS, VPS cleanup, package update on the VPS
Core principle — containment before autonomy
Autonomy is a byproduct of containment, not a goal in itself. A well-designed autonomous agent is not the smartest one — it is the one that, even when it errs or hallucinates, cannot reach beyond a bounded, reversible domain. Autonomy without guardrails is not Jarvis; it is a fire. Every rule below exists to bound blast radius while keeping the agent ungimped.
The agent is invoked, not unattended. It runs when the user calls it — a human supervisor in the loop. Deterministic repetitive work (restarts, backups, log rotation) belongs to VPS crons, not the agent. Do not ask a probabilistic brain to do a clock's job.
Strategy rationale and the decision record live in
docs/research/autonomous-vps-mechanism.md (this repo). This skill is the operating law; the
blueprint is the why. Do not duplicate the blueprint here.
Process
Step 1 — Establish the source-of-truth mesh
The canonical repo lives on GitHub. The VPS holds only working clones. The VPS can burn without data loss. Never treat the VPS as the only copy of code — that is the single point of failure this whole method exists to avoid.
Step 2 — Deploy via GitOps, never agent-driven
The agent has code power, not production power. It programs and pushes to GitHub; a GitOps engine (Coolify by default) picks up the change and deploys with healthcheck + rollback.
- Flow: agent programs → push to GitHub → webhook → engine builds, healthchecks, deploys if pass, rolls back if fail, exposes logs/state in a UI.
- The engine is the agent's tool for app deploys — the agent governs app deploys through it, so every production change carries a healthcheck and a rollback. The agent never hand- deploys to production.
- Model prod/test as branch-per-environment:
main→ production,develop/staging→ staging. Each environment has its own containers, DB, and variables. Promote test→prod by adevelop → mainmerge — auditable, reversible.
Step 3 — Govern the machine from a contained seat
The agent governs the VPS broadly — Docker, services, cleanup, package updates, hot-changes — from a dedicated admin container (Docker socket mounted + code workspace on a volume), not as root on the bare host. Same full governance; a filesystem finger-error stays contained in the container instead of nuking the host. The container is the agent's seat, not its cage.
Step 4 — Guard by behavior, confirm at the irreversible edge
Restriction is by confirmation, not roles. The agent CAN do everything; it must ask before
the catastrophic-irreversible actions listed in Rules. This is a behavioral guard (governed by
CLAUDE.md), the same mechanism that already stops the agent from reading a .env. OS
roles/permissions are a fallback, reserved only for a future catastrophic case — do not
impose them by default (a hamstrung admin is the failure mode, not the goal).
Secrets live in the deploy engine (per-environment, encrypted, injected at runtime). The agent sets and references them by name only — a secret NEVER enters the agent's context in plaintext nor leaves in a response. The agent operates on references, not values.
Step 5 — Back up with a verified, off-site, agnostic method
Data loss is the one thing that never reverses — back up with full rigor even at zero users.
- Core = logical dump (
pg_dump/mysqldump/mongodumpper engine), executed by a deterministic VPS cron. The agent designs, verifies, and restores under invocation. - 3-2-1: the dump must go off-site (leave the VPS). A backup on the same VPS as the DB dies with it.
- Retention with rotation (e.g. 7 daily + 4 weekly).
- Verified restore is part of the method — a backup never test-restored does NOT count; it is hope, not a backup. The agent periodically test-restores under invocation.
- Prefer logical dump over volume snapshots (fragile, version/engine-locked) and over replica/PITR (defer that as the explicit upgrade for when real users exist).
- If the DB is managed (e.g. Supabase), the provider backs up — the method only verifies.
Step 6 — Monitor on demand, in two layers
Fewer good signals beat many signals; an agent drowning in logs hallucinates.
- Layer 1 (passive): the deploy engine's UI shows container state, logs, deploy health, resource usage — always on, free.
- Layer 2 (invoked): the agent runs a short, curated set of health checks on request (disk usage, memory, down containers, recent errors, backup status) and summarizes. Not a continuous stream.
- Proactive/unattended alerts, if ever wanted, are a cron that pings — never the agent watching 24/7.
Rules
- Scope split (non-negotiable): this skill is the agnostic method; the concrete stack (engine config, Docker commands, dump scripts, webhook wiring) lives in the consumer VPS repo, never in this skill. Naming an engine (Coolify) as a default does not make the method engine-specific.
- Source of truth is GitHub; the VPS holds clones only. Never make the VPS the sole copy.
- The agent has code power, not production power. Never hand-deploy to production — always through the GitOps engine, so healthcheck + rollback apply.
- Governance runs from a contained admin container, never as root on the bare host by default.
- Confirm before these catastrophic-irreversible actions (behavioral guard, not roles):
- delete/prune a data volume or drop a database;
rm -rf(or equivalent destructive fs op) outside the code workspace;- take down / reconfigure the deploy engine itself;
- read, write, or rotate credentials/secrets in a way that could expose them;
- force-push or rewrite history on a
main/productionbranch; - destroy or recreate the admin container the agent runs in. Everything else is free — do not gate ordinary work.
- Secrets are referenced by name only — never read back in plaintext, never echoed in a response, never committed.
- Backups are cron-executed, off-site, rotated, and verified by test-restore. An unverified backup does not count.
- The agent is invoked, not unattended; deterministic repeated work is a cron's job.
- This skill governs HOW the agent operates a VPS, not WHAT stack runs on it — inject no stack-specific opinion as if it were method.