docs: Document the boxes

Add a top-level `README.md` mapping the boxes and per-machine docs under
`docs/boxes/` (grouped `colony/`, `home/`, `misc/`), one file per host, VM and
container documenting role, services and networking with source pointers.

Also point `AGENTS.md` at the new docs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/boxes/colony/README.md

@@ -0,0 +1,68 @@
+# colony
+
+The hosted dedicated server in Amsterdam (`ams1`). This is the public-facing
+half of the boxes: almost everything reachable from the internet lives here.
+
+- **Internal domain:** `ams1.int.nul.ie`
+- **Public domain:** `nul.ie` (public services are published as `*.nul.ie`)
+- **Source:** [`nixos/boxes/colony/`](../../../nixos/boxes/colony)
+
+## Shape
+
+`colony` is the physical VM host. It runs the VMs below; one of them (`shill`)
+is itself a NixOS container host where most applications run.
+
+```
+colony (physical VM host)
+├── estuary ── edge router / firewall / DNS / BGP
+├── shill ──── NixOS container host ──┬── middleman    (reverse proxy, ACME, SSO)
+│                                     ├── colony-psql  (shared PostgreSQL)
+│                                     ├── vaultwarden  (password manager)
+│                                     ├── chatterbox   (Matrix + bridges)
+│                                     ├── toot         (Mastodon)
+│                                     ├── jackflix     (media stack)
+│                                     ├── object       (MinIO, Nix cache, …)
+│                                     ├── waffletail   (Tailscale subnet router)
+│                                     ├── qclk         (clock service)
+│                                     └── gam          (game servers)
+├── whale2 ─── podman/OCI host (game servers)
+├── git ────── Gitea + Actions runner
+├── mail ───── Debian VM running Mailcow (not NixOS — configured out of repo)
+└── darts ──── third-party/customer VM (opaque to this repo)
+```
+
+## Machines
+
+| Machine | Role | Docs |
+| --- | --- | --- |
+| `colony` | Physical VM host (AMD, LVM-thin, borgthin backups → rsync.net) | [colony.md](colony.md) |
+| `estuary` | Edge router: WAN, firewall/NAT, DNS, BGP, IXP peering, WireGuard | [estuary.md](estuary.md) |
+| `shill` | NixOS container host (see containers below) | [shill.md](shill.md) |
+| `whale2` | podman/OCI host for game servers | [whale2.md](whale2.md) |
+| `git` | Gitea + Gitea Actions runner | [git.md](git.md) |
+
+### shill containers
+
+| Container | Role | Docs |
+| --- | --- | --- |
+| `middleman` | Front-end nginx reverse proxy, ACME certs, nginx-sso, librespeed | [middleman.md](middleman.md) |
+| `colony-psql` | Shared PostgreSQL (14) for colony services | [colony-psql.md](colony-psql.md) |
+| `vaultwarden` | Vaultwarden (Bitwarden-compatible password manager) | [vaultwarden.md](vaultwarden.md) |
+| `chatterbox` | Matrix homeserver + bridges (heisenbridge, mautrix-*) | [chatterbox.md](chatterbox.md) |
+| `toot` | Bluesky PDS (Mastodon disabled) | [toot.md](toot.md) |
+| `jackflix` | Media: Jellyfin, *arr stack, Transmission, PhotoPrism, copyparty | [jackflix.md](jackflix.md) |
+| `object` | MinIO (S3), Harmonia (Nix cache), HedgeDoc, wastebin | [object.md](object.md) |
+| `waffletail` | Tailscale subnet router (advertises colony prefixes into the tailnet) | [waffletail.md](waffletail.md) |
+| `qclk` | `qclk` clock service (reachable over WireGuard) | [qclk.md](qclk.md) |
+| `gam` | Game servers (Terraria, …) | [gam.md](gam.md) |
+
+## Non-NixOS VMs
+
+These run on `colony` but are **not** managed by this repo (no NixOS config). The
+QEMU instances are still declared in `colony`'s `my.vms.instances`, and colony's
+networking routes/firewalls traffic to them:
+
+- **`mail`** — a Debian VM running [Mailcow](https://mailcow.email/) (`mail.nul.ie`).
+  ACME certs are pushed to it from `middleman` (see [middleman.md](middleman.md)).
+- **`darts`** — a third-party/customer VM; opaque to this repo, given a routed
+  prefix and otherwise left alone.

docs/boxes/colony/chatterbox.md

@@ -0,0 +1,19 @@
+# chatterbox
+
+The Matrix homeserver (`nul.ie`) and its chat-network bridges.
+
+- **Source:** [`shill/containers/chatterbox.nix`](../../../nixos/boxes/colony/vms/shill/containers/chatterbox.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Matrix homeserver** for `server_name = "nul.ie"`.
+- **Bridges** to other chat networks:
+  - `heisenbridge` (IRC),
+  - `mautrix-whatsapp` (WhatsApp),
+  - `mautrix-meta` / `mautrix-messenger` (Facebook Messenger / Instagram).
+- Fronted by `middleman` (federation on `:8448`).
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `chatterbox-ctr`).

docs/boxes/colony/colony-psql.md

@@ -0,0 +1,18 @@
+# colony-psql
+
+The shared PostgreSQL instance for colony. Several other containers
+(`middleman`, `chatterbox`, `toot`, `git`, …) connect here rather than each
+running their own database.
+
+- **Source:** [`shill/containers/colony-psql.nix`](../../../nixos/boxes/colony/vms/shill/containers/colony-psql.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **PostgreSQL 14** serving the other colony services over the `ctrs` network.
+  Consumers wait for it to be ready via the `systemdAwaitPostgres` helper.
+- netdata for monitoring.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `colony-psql-ctr`).

docs/boxes/colony/colony.md

@@ -0,0 +1,39 @@
+# colony (host)
+
+The physical dedicated server in Amsterdam and the VM host for everything in
+this group.
+
+- **Source:** [`nixos/boxes/colony/default.nix`](../../../nixos/boxes/colony/default.nix)
+  (VM instances in [`nixos/boxes/colony/vms/default.nix`](../../../nixos/boxes/colony/vms/default.nix))
+- **nixpkgs:** `mine-stable`
+
+## Role
+
+Bare-metal AMD host. It does little application work itself — its job is to run
+the VMs and provide them with storage, networking and backups.
+
+- **Virtualisation:** QEMU/KVM (`kvm-amd`, IOMMU on) via the `my.vms` module. VM
+  disks are LVM logical volumes (`vm-<name>-<disk>`) in the `main` volume group;
+  `estuary` additionally gets a WAN NIC by PCI passthrough.
+- **Storage:** LVM-thin (`services.lvm.boot.thin`), `/persist` for state,
+  `/mnt/backup` for the local borg repo. `smartd` + `rasdaemon` for health.
+- **Backups:** `my.borgthin` snapshots the persist/data LVs of the host and its
+  VMs into `/mnt/backup/main`, which is then `rsync`'d (along with LVM metadata)
+  to rsync.net (`zh2855.rsync.net`).
+- **Monitoring:** netdata (with freeipmi), smartd.
+
+## Networking
+
+- Two bridges: `base` (the colony "base" network, shared with `estuary`) and
+  `vms` (the VM network). Dummy interfaces keep the bridges up so dependent VMs
+  can start.
+- Default gateway / edge is `estuary`; `colony` itself holds the `routing` and
+  `internal` (a.k.a. `vm`) assignments and routes container/OCI/Tailscale
+  prefixes to `shill` and `whale2`.
+- `my.firewall` trusts the `vms` interface and forwards customer prefixes
+  (`vm-mail`, `vm-darts`) through.
+
+## VMs hosted here
+
+`estuary`, `shill`, `whale2`, `git` (all NixOS, documented in this directory),
+plus the non-NixOS `mail` and `darts` (see [README](README.md#non-nixos-vms)).

docs/boxes/colony/estuary.md

@@ -0,0 +1,41 @@
+# estuary
+
+The colony edge router and firewall — the machine that holds colony's public
+IPs and connects everything else to the internet.
+
+- **Source:** [`nixos/boxes/colony/vms/estuary/`](../../../nixos/boxes/colony/vms/estuary)
+  (`default.nix`, `bgp.nix`, `dns.nix`, `bandwidth.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony` (gets the WAN NIC by PCI passthrough)
+
+## Role
+
+- **Edge routing / firewall / NAT:** owns the colony public IPv4/IPv6
+  (`94.142.241.x` / `2a02:898:0:20::`), does NAT and port-forwarding for the
+  internal services (`my.firewall.nat.forwardPorts` driven by
+  `firewallForwards`). Forwards HTTP/S to `middleman`, git to `git`, game ports
+  to the OCI game servers on `whale2`, etc.
+- **BGP:** runs BIRD2 ([`bgp.nix`](../../../nixos/boxes/colony/vms/estuary/bgp.nix))
+  announcing AS211024, over VLANs on the WAN link:
+  - peers at the IXPs **Frys-IX**, **NL-ix** and **FogIXP**;
+  - plus **iFog transit** (`ifog-transit`) — an upstream transit provider from
+    iFog, **not** an IXP.
+- **DNS:** authoritative/recursive DNS ([`dns.nix`](../../../nixos/boxes/colony/vms/estuary/dns.nix)),
+  redirected to port 5353 locally.
+- **VPNs:**
+  - Part of the AS211024 **L2 VXLAN mesh** (`my.vpns.l2`) with `river`, `stream`
+    and `britway`.
+  - WireGuard endpoints for the remote `kelder` site, `hillcrest`, and
+    `john-valorant`.
+- **Misc:** iperf3 server. (A bandwidth-accounting script,
+  [`bandwidth.py`](../../../nixos/boxes/colony/vms/estuary/bandwidth.py), exists but
+  is **legacy and not currently used**.)
+
+## Networking
+
+- `wan` — the passed-through igb NIC (9000 MTU), carrying the upstream uplink and
+  tagged IXP VLANs (`ifog` 409 → `frys-ix`/`nl-ix`/`fogixp`/`ifog-transit`).
+- `base` — colony base network; sends RAs and provides DNS to the base prefix,
+  routes the VM/container/OCI/Tailscale prefixes back to `colony`.
+- `as211024` — the L2 mesh interface.
+- Assignments: `internal` (public, alt name `fw`), `base`, `as211024`.

docs/boxes/colony/gam.md

@@ -0,0 +1,17 @@
+# gam
+
+A game-server container (the lightweight counterpart to the OCI game servers on
+`whale2`).
+
+- **Source:** [`shill/containers/gam.nix`](../../../nixos/boxes/colony/vms/shill/containers/gam.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Hosts game servers run directly as NixOS services — currently **Terraria**
+  (config/world from secrets). Exposed to the internet via `estuary`'s port
+  forwards (`:7777`).
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `gam-ctr`).

docs/boxes/colony/git.md

@@ -0,0 +1,38 @@
+# git
+
+The Gitea VM — source hosting and CI for the boxes (`git.nul.ie`).
+
+- **Source:** [`nixos/boxes/colony/vms/git/`](../../../nixos/boxes/colony/vms/git)
+  (`default.nix`, `gitea.nix`, `gitea-actions.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony`
+
+## Role
+
+- **Gitea** ([`gitea.nix`](../../../nixos/boxes/colony/vms/git/gitea.nix)) — the Git
+  forge (`git.nul.ie`). PostgreSQL-backed (the shared `colony-psql`), LFS
+  enabled, with object storage backed by MinIO on `object` (a MinIO secret is
+  spliced into `app.ini` at startup).
+- **Gitea Actions runner**
+  ([`gitea-actions.nix`](../../../nixos/boxes/colony/vms/git/gitea-actions.nix)) — a
+  Docker-mode runner (`main-docker`) using podman. Labels provide Debian/node-24
+  (Trixie) and Ubuntu 26.04 images; runner config comes from the upstream
+  module's `settings` option. The Actions cache lives on a dedicated disk
+  (`/var/cache/gitea-runner`). Runs as a fixed `gitea-runner` user (not
+  `DynamicUser`) so it can read its token.
+- **nginx** — terminates TLS for `git.nul.ie` and proxies to Gitea on `:3000`.
+  ACME certs for `nul.ie` / `*.nul.ie` via the Cloudflare DNS challenge.
+- **podman** — also hosts the OCI registry/build images; `/var/lib/containers`
+  is an XFS data disk.
+
+## Networking
+
+- `vms` interface with `routing` / `internal` assignments.
+- HTTP/HTTPS forwarded in from `estuary`; podman default subnet `10.88.0.0/16` is
+  allowed to forward.
+
+## CI
+
+This runner is what executes the repo's own `.gitea/workflows/ci.yaml`, building
+each `.#ci.x86_64-linux` attribute and pushing to the Harmonia binary cache. See
+[`AGENTS.md`](../../../AGENTS.md#commands).

docs/boxes/colony/jackflix.md

@@ -0,0 +1,25 @@
+# jackflix
+
+The media stack — acquisition, library and streaming.
+
+- **Source:** [`shill/containers/jackflix/`](../../../nixos/boxes/colony/vms/shill/containers/jackflix)
+  (`default.nix`, `networking.nix`)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Streaming:** Jellyfin.
+- **Acquisition (*arr stack):** Transmission, Jackett, FlareSolverr, Radarr,
+  Sonarr, and Jellyseerr (`seerr`) for requests.
+- **Photos:** PhotoPrism (`photos.nul.ie`).
+- **File sharing:** copyparty (`:3923`) serving public + private media volumes.
+- Media lives on the shared `/mnt/media` volume (bind-mounted read-write from
+  `shill`). Downloaders bind to a VPN interface
+  ([`networking.nix`](../../../nixos/boxes/colony/vms/shill/containers/jackflix/networking.nix)),
+  so torrent traffic only flows while `systemd-networkd-wait-online@vpn` is up.
+- A shared `media` group (gid 2000) gives the apps coordinated access.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `jackflix-ctr`), plus its
+  own VPN interface for the download clients.

docs/boxes/colony/middleman.md

@@ -0,0 +1,63 @@
+# middleman
+
+The front-end reverse proxy for all public colony web services — the single
+ingress that `estuary` forwards HTTP/HTTPS to.
+
+- **Source:** [`shill/containers/middleman/`](../../../nixos/boxes/colony/vms/shill/containers/middleman)
+  (`default.nix`, `vhosts.nix`)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **nginx** reverse proxy ([`vhosts.nix`](../../../nixos/boxes/colony/vms/shill/containers/middleman/vhosts.nix)
+  holds the per-service vhosts) with VTS stats, fancyindex, brotli, caching, and
+  a dynamic resolver pointed at `estuary` so upstreams can be re-resolved at
+  runtime. It is the single public ingress for almost every web service — colony,
+  home, and beyond.
+- **ACME** — issues the wildcard certificates that **its own** vhosts are served
+  with (it is not a shared CA for the other boxes; `git`, `britway`, `kelder-spoder`, etc. each
+  run their own ACME):
+  - `nul.ie` / `*.nul.ie` (+ `*.s3.nul.ie`) via the Cloudflare DNS challenge,
+  - the internal `ams1.int.nul.ie` / `*` via an `exec` challenge that calls
+    `estuary`'s pdns over SSH.
+  - As a one-off consumer, it then pushes the public cert to the `mail` (Mailcow)
+    VM via `scp` + a remote `mailcow-ssl-reload`.
+- **nginx-sso** — single-sign-on (`sso.nul.ie`) with Google OAuth and a simple
+  username/password provider; protects the SSO-gated vhosts below.
+- **librespeed** — speed-test frontend + backend (`librespeed.${domain}` /
+  `speed.nul.ie`).
+
+## Published vhosts
+
+All under `*.nul.ie` with the wildcard cert unless noted. Upstreams are addressed
+by their internal container/VM hostnames. "SSO" = gated behind nginx-sso.
+
+| Host(s) | Upstream | Notes |
+| --- | --- | --- |
+| `nul.ie` (default `_`) | static | landing page (CV, SSH pubkey) + Matrix/atproto `.well-known` |
+| `sso.nul.ie` | nginx-sso | SSO endpoint |
+| `pass.nul.ie` | `vaultwarden` | password manager |
+| `matrix.nul.ie` (+`:8448`) | `chatterbox` | Matrix client + federation |
+| `element.nul.ie` | element-web | Matrix web client |
+| `toot.nul.ie` | `toot` :80 | Mastodon (currently disabled — see [toot.md](toot.md)) |
+| `pds.nul.ie` | `toot` :3000 | Bluesky PDS |
+| `jackflix.nul.ie` | `jackflix` Jellyfin | streaming |
+| `torrents` / `jackett` / `radarr` / `sonarr` `.nul.ie` | `jackflix` | *arr stack (**SSO**) |
+| `gib.nul.ie` | `jackflix` Jellyseerr | requests |
+| `photos.nul.ie` | `jackflix` PhotoPrism | |
+| `stuff` / `public` / `p.nul.ie` | `jackflix` copyparty + `/mnt/media` | file sharing / index |
+| `share.nul.ie` | `object` :9090 | |
+| `minio` / `s3` / `*.s3.nul.ie` | `object` MinIO | S3 + console (Docker manifest MIME hack) |
+| `nix-cache.nul.ie` | `object` Harmonia | Nix binary cache (immutable cache headers) |
+| `md.nul.ie` / `pb.nul.ie` | `object` | HedgeDoc / wastebin |
+| `mc-map` / `mc-rail` / `mc-map-kink` `.nul.ie` | `whale2` OCI | Minecraft maps |
+| `netdata-colony.nul.ie` | many hosts :19999 | netdata fan-out (**SSO**) |
+| `pront.nul.ie` | `stream-hi` (home) | print/webcam (**SSO**) |
+| `hass.nul.ie` | `hass` (home) | Home Assistant |
+| `hass-john.nul.ie` | `john-valorant-tun` | remote HASS over WireGuard tunnel |
+
+## Networking
+
+- `internal` assignment on the `ctrs` network; bind-mounts `/mnt/media` for
+  serving static/media content.
+- nginx waits for `colony-psql` before starting (DNS bootstrap hack).

docs/boxes/colony/object.md

@@ -0,0 +1,24 @@
+# object
+
+Object storage and Nix binary cache, plus a couple of small self-hosted web
+apps.
+
+- **Source:** [`shill/containers/object.nix`](../../../nixos/boxes/colony/vms/shill/containers/object.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **MinIO** — S3-compatible object storage (`s3.nul.ie` / `*.s3.nul.ie`). Backs
+  several other services (Gitea LFS/artifacts, social-media uploads, …). Stored on the
+  `/mnt/minio` volume (XFS, bind-mounted from `shill`).
+- **Harmonia** — serves the Nix binary cache for all the boxes (`nix-cache.nul.ie`), backed
+  by the `/mnt/nix-cache` volume.
+- **atticd** — an alternative Nix cache (stores into MinIO/S3). **Currently
+  disabled** — present in the config but not running.
+- **HedgeDoc** — collaborative markdown notes.
+- **wastebin** — pastebin.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `object-ctr`).
+- `/mnt/minio` and `/mnt/nix-cache` bind-mounted read-write from `shill`.

docs/boxes/colony/qclk.md

@@ -0,0 +1,22 @@
+# qclk
+
+The `qclk` service container.
+
+- **Source:** [`shill/containers/qclk/`](../../../nixos/boxes/colony/vms/shill/containers/qclk)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Runs the custom `qclk` service, exposing an API that is reached over a
+  dedicated WireGuard **`management`** network. Managed devices are configured as
+  WireGuard peers (each gets an address in the `qclk` prefix), and AS211024
+  trusted hosts are allowed to reach the API.
+- `shill` routes the `qclk` prefix to this container.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `qclk-ctr`), plus the
+  `management` WireGuard interface carrying the `qclk` prefix.
+
+> Check `qclk/default.nix` for the current peer list and exactly what the service
+> does — this entry intentionally stays high-level.

docs/boxes/colony/shill.md

@@ -0,0 +1,48 @@
+# shill
+
+The colony **NixOS container host**. Most colony applications run as
+systemd-nspawn containers on `shill`.
+
+- **Source:** [`nixos/boxes/colony/vms/shill/`](../../../nixos/boxes/colony/vms/shill)
+  (`default.nix`, `containers-ext.nix`, `hercules.nix`, `containers/`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony` (large: 12 cores, 40 GiB RAM)
+
+## Role
+
+- Runs the colony NixOS containers via `my.containers.instances`, each attached
+  to the `ctrs` bridge with its own address.
+- Provides shared data volumes to those containers via bind mounts from
+  LVM-backed disks: `/mnt/media` (→ `middleman`, `jackflix`), `/mnt/minio` and
+  `/mnt/nix-cache` (→ `object`).
+- Acts as the router between the `vms` network and the `ctrs` container network
+  (sends RAs on `ctrs`, routes Tailscale prefixes via `waffletail` and the
+  `qclk` prefix via `qclk`). Includes an nftables `ct mark` hack to make
+  internal DNAT return paths work.
+- Tuned sysctls for high connection counts / torrent traffic; netdata.
+
+## Containers
+
+Defined in [`shill/containers/`](../../../nixos/boxes/colony/vms/shill/containers)
+and wired up in `shill`'s `my.containers.instances`:
+
+| Container | Role |
+| --- | --- |
+| [`middleman`](middleman.md) | Front-end nginx reverse proxy, ACME, nginx-sso, librespeed |
+| [`colony-psql`](colony-psql.md) | Shared PostgreSQL |
+| [`vaultwarden`](vaultwarden.md) | Password manager |
+| [`chatterbox`](chatterbox.md) | Matrix homeserver + bridges |
+| [`toot`](toot.md) | Bluesky PDS (Mastodon disabled) |
+| [`jackflix`](jackflix.md) | Media stack |
+| [`object`](object.md) | MinIO / Harmonia / HedgeDoc / wastebin |
+| [`waffletail`](waffletail.md) | Tailscale subnet router |
+| [`qclk`](qclk.md) | Clock service |
+| [`gam`](gam.md) | Game servers |
+
+## Notes
+
+- Container systems set `my.deploy.enable = false` (they are deployed as part of
+  `shill`'s container profiles, not as standalone deploy nodes) and render via
+  `my.asContainer`.
+- `hercules.nix` configures Hercules CI agent bits;
+  `containers-ext.nix` holds extra per-container host wiring.

docs/boxes/colony/toot.md

@@ -0,0 +1,19 @@
+# toot
+
+A federated-social container. Despite the name (Mastodon = "toots"), it currently
+hosts a **Bluesky PDS**; the Mastodon instance is disabled.
+
+- **Source:** [`shill/containers/toot.nix`](../../../nixos/boxes/colony/vms/shill/containers/toot.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- **Bluesky PDS** (Personal Data Server) — the active service, published as
+  `pds.nul.ie` (proxied by `middleman` to `:3000`).
+- **Mastodon** — **currently disabled**. The config is still present and
+  `toot.nul.ie` still maps to `:80`, but the instance is not running. (It was
+  backed by the shared `colony-psql` and MinIO/S3 on `object`.)
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `toot-ctr`).

docs/boxes/colony/vaultwarden.md

@@ -0,0 +1,15 @@
+# vaultwarden
+
+[Vaultwarden](https://github.com/dani-garcia/vaultwarden), a Bitwarden-compatible
+password manager.
+
+- **Source:** [`shill/containers/vaultwarden.nix`](../../../nixos/boxes/colony/vms/shill/containers/vaultwarden.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Runs Vaultwarden, fronted by `middleman` and published under `nul.ie`.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `vaultwarden-ctr`).

docs/boxes/colony/waffletail.md

@@ -0,0 +1,19 @@
+# waffletail
+
+The colony Tailscale node / subnet router.
+
+- **Source:** [`shill/containers/waffletail.nix`](../../../nixos/boxes/colony/vms/shill/containers/waffletail.nix)
+- **Host:** NixOS container on `shill`
+
+## Role
+
+- Joins the Tailscale tailnet (auth key from secrets) and **advertises the colony
+  prefixes** into it, acting as the subnet router so tailnet clients can reach
+  colony services and vice-versa.
+- nftables rules SNAT/forward between `host0` and `tailscale0` for the colony
+  v4/v6 ranges. `shill` routes the Tailscale prefixes here.
+
+## Networking
+
+- `internal` assignment on the `ctrs` network (alt name `waffletail-ctr`); owns
+  the `tailscale0` interface.

docs/boxes/colony/whale2.md

@@ -0,0 +1,27 @@
+# whale2
+
+A podman/OCI host on colony dedicated to game servers (kept off `shill` so the
+container churn and resource use stay isolated).
+
+- **Source:** [`nixos/boxes/colony/vms/whale2/`](../../../nixos/boxes/colony/vms/whale2)
+  (`default.nix`, `valheim.nix`, `minecraft/`, `enshrouded.nix`)
+- **nixpkgs:** `mine`
+- **Host:** VM on `colony`
+
+## Role
+
+- Runs OCI containers via **podman** (`virtualisation.oci-containers`, netavark
+  backend) on a dedicated `colony` bridge network (`oci`) with both IPv4 and
+  IPv6, so each game server gets its own routable address.
+- Game servers configured in-repo: **Valheim**, **Minecraft** (several worlds —
+  see `extraAssignments`: `simpcraft`, `simpcraft-staging`, `kevcraft`,
+  `kinkcraft`, `graeme`), and **Enshrouded** (currently commented out).
+- `/var/lib/containers` is an XFS data disk (project quotas).
+
+## Networking
+
+- `vms` interface with `routing` / `internal` (alt name `oci`) assignments.
+- An `oci` bridge carrying the `prefixes.oci` v4/v6 ranges; per-game addresses
+  are handed out via `extraAssignments` (`valheim-oci`, `simpcraft-oci`, …) and
+  exposed to the internet through `estuary`'s port forwards.
+- Firewall trusts the `oci` interface and forwards `vms → oci`.