Pets

Minimalist configuration management for "pet" Debian Linux servers. Declare intent with primitives, group primitives into a role, then check/apply across a fleet.

🤖 experimental 🤖

This was built to learn about swamp extensions, don't use it!

Every model takes a fleet (@swamp/ssh model instance), and a hosts selector (all, name:X, tag:Y). Convergence logic streams to each host's python3 over SSH stdin; nothing is installed on the targets. check is read-only; apply converges with sudo. Statuses: compliant, non_compliant, applied (real changes made), failed.

Quickstart by example: PostgreSQL from PGDG repositories

Define a fleet:

swamp extension pull @swamp/ssh
swamp model create @swamp/ssh my-fleet
swamp model edit my-fleet

transport:
  kind: ssh
  user: debian
  identityFile: ~/.ssh/id_ed25519
hosts:
  - name: build
    address: build.example.com
    tags: [build]

Declare our APT repository (see: PGDG):

swamp model create @psftw/pets/apt-repository pgdg-repo
swamp model edit pgdg-repo

fleet: my-fleet
name: pgdg-repo
uris: [https://apt.postgresql.org/pub/repos/apt]
suites: [trixie-pgdg]
components: [main]
gpgKeyUrl: https://www.postgresql.org/media/keys/ACCC4CF8.asc
signedBy: /etc/apt/keyrings/pgdg.asc

Declare our package install:

swamp model create @psftw/pets/apt postgres-package
swamp model edit postgres-package

fleet: my-fleet
packages:
  - postgresql-18

Sequence these into a role:

swamp model create @psftw/pets/role postgres-role
swamp model edit postgres-role

fleet: my-fleet
members:
  - pgdg-repo
  - postgres-package

Apply the role to our server:

swamp model method run postgres-role apply --input hosts=all
[INF] @psftw/pets/role·apply: [1/2] pgdg-repo: apply on all
[INF] @psftw/pets/apt-repository·apply: running on all via my-fleet (sudo)
[INF] @psftw/pets/apt-repository·apply: build: applied — write /etc/apt/sources.list.d/pgdg-repo.sources; fetch key to /etc/apt/keyrings/pgdg.asc
[INF] @psftw/pets/role·apply: [1/2] pgdg-repo: applied=1
[INF] @psftw/pets/role·apply: [2/2] postgres-package: apply on all
[INF] @psftw/pets/apt·apply: running on all via my-fleet (sudo)
[INF] @psftw/pets/apt·apply: build: applied — install postgresql-18
[INF] @psftw/pets/role·apply: [2/2] postgres-package: applied=1
[INF] @psftw/pets/role·apply: build: applied — pgdg-repo: write /etc/apt/sources.list.d/pgdg-repo.sources; pgdg-repo: fetch key to /etc/apt/keyrings/pgdg.asc; postgres-package: install postgresql-18
[INF] @psftw/pets/role·apply: summary[all]: applied

View the compliance report:

swamp report get @psftw/pets/fleet-compliance --model postgres-role

Fleet compliance — postgres-role · apply (succeeded)

Aggregate: applied across 1 host(s) — selector all — 2026-08-11T00:00:00.000Z

Members

Changes

• build: pgdg-repo: write /etc/apt/sources.list.d/pgdg-repo.sources
• build: pgdg-repo: fetch key to /etc/apt/keyrings/pgdg.asc
• build: postgres-package: install postgresql-18

Fix: template-file apply converged owner/group/mode silently when the content hash already matched, reporting compliant with no changes recorded. It now touches owner/mode only when drifted, reports the run as applied, and records each chown/chmod in changes; apply facts gained a performed list. changed still means content changed, so onChange semantics are unaffected.