AGENTS.md — KNEL/cloudron (tsys-cloudron / my.knownelement.com)

Fleet-machine repo for the production Cloudron host. Layering: global ~/.zcode/AGENTS.md < KNEL/PFVCluster/AGENTS.md < this file. The global rules (ticket-governed work, push-as-you-go, Discourse as doc SoR, secrets in ~/.creds only) all apply; this file adds host specifics only.

Agent authority (non-negotiable)

No work without an approved Redmine ticket (project 88, Cloudron). Ticket-first: echo '#NNN' > .crush/active-ticket.
Propose, never implement — findings become Feedback sub-tickets.
NEVER close a ticket; NEVER 100% done-ratio — founder UAT gates "done".
Production mutations only when the ticket says so; rollback documented in the ticket BEFORE the change (see #685 notes for the pattern).

Access (SSH-only, NON-NEGOTIABLE)

SSH root@my.knownelement.com is the ONLY access path. No panel back-channels, no guest-agent (qemu guest exec is banned fleet-wide).

ALL ssh/scp routes through the chokepoint (from a PFVCluster checkout):

VM_IP=my.knownelement.com VM_USER=root bash tests/remote.sh vm '<cmd>'      # quick reads, timeout 30
VM_IP=my.knownelement.com VM_USER=root bash tests/remote.sh vm-file <script> # deploy/run a script

DNS names only — never IP literals.
API-first goal: Cloudron API token pending (asks #685/#727). Once issued it lives as a ref in ~/.creds/cloudron.env; prefer the panel API over shell once available. Cloudron CLI on the host (cloudron machine/?) — not set up.

Applied-state SoR (details in perf/ + Discourse t/316)

Postgres: max_connections=700, shared_buffers 2GB, idle_in_transaction_session_timeout=15min, role caps (default 20 / booking 10 / penpot 15). Re-apply script: perf/pg-role-caps.sql.
sysctl: perf/sysctl/99-cloudron-tuning.conf (vm.swappiness=10).
docker daemon.json NOT yet applied — perf/docker-daemon.json.planned needs a human-chosen dockerd bounce window (restarts ALL containers; live-restore=false today). Postgres nofile bridge (prlimit 262144) is EPHEMERAL until then.

Repo rules

shellcheck zero-warning (incl. info): bash tests/shellcheck.sh
Enforcement: scripts/check-rules.sh; install hooks: bash scripts/setup-hooks.sh
Docs on Discourse (perf: t/316); .md files here are pointers, not SoR.
Commits: conventional format, [#NNN] ref, short body with clickable Redmine comment URL. The meat goes in the ticket comment, same turn.

Resource-adjustment policy (ratified 2026-09-02)

Agent-approvable: app memory increases only — justified (>80% utilization or 24h memcg OOM), sized ~2x usage, above manifest floor, exclusions respected (bi.knownelement.com, platform services), verified + documented same-day. Human-required: any decrease, platform/Postgres/mail tuning, CPU/disk classes, repeat-OOM escalations. Full text: Discourse t/317 · Redmine #735.

2.9 KiB Raw Permalink Blame History