EXTENSIONS

Build, push, and inspect OCI container images. Registry-agnostic — works with ECR, GHCR, DockerHub, or any OCI-compliant registry. Supports docker, podman, nerdctl, and buildah. Produces typed, versioned build metadata.

The headless runtime of the session-* suite. Runs a filled analysis template — R/qmd in a pinned nix R env (`run`), a targets pipeline via a harvester (`run-targets`), or Python/ipynb via papermill in the locked conda/Docker env (`run-notebook`) — with the recorder armed or a swamp.returns contract verified. Also faithfully REPLAYS a captured session: `replay` re-runs recorded R against frozen tolerance rules (nix preferred, docker fallback), and the Python host-replay shim serves a captured session's host.* calls offline (or falls through to the live API in hybrid mode). Reproduce a governed run — or a foreign Claude Science session — deterministically.

Take a single base OCI image identifier and emit its security-patched counterpart under the HiveMQ naming convention (<registry>/<namespace>/<flattened>:<tag>-hivemq-patched-<date>). A pure logic model (`plan` generates the security-upgrade Dockerfile + derives the re-homed target; `verify` asserts the expected fixed package versions) plus a bundled workflow that orchestrates a container CLI wrapper around it: plan, build the multi-arch image, verify the expected versions on every platform of it, then push. Two workflow variants ship: the Apple @hivemq/container engine (self-hosted macOS) and @hivemq/docker (standard Linux/GitHub-hosted runners). Motivated by PLT-941 (openssl CVE-2026-45447): own the patch cadence instead of waiting on upstream base rebuilds. Registry credentials are injected from a swamp vault at run time and never persisted in a committed instance.

Thin swamp wrapper around the `docker` CLI. Image-lifecycle subset: `build` (single-platform, locally runnable), `run`, `buildInspectPlatforms` (build each arch single-arch with `buildx --load` + run an inspection command, capturing all output in one `inspected` resource — the verify-before-push primitive), `login`, and `buildx build --push` (multi-arch build + push). Each method mirrors a `docker` subcommand so workflows can drive the build/run/publish lifecycle without bespoke shell steps.

A declared fleet of base OCI images we keep security-patched. The whole job — what to patch (`source` = registry/repository/tag), how (`patch`, default: apply all pending security updates), where to publish (`destination` = repository/tag under a run-time `registry`), and what to assert (`expect`, optional version floor) — lives in the model instance's `globalArguments.images`, so a single `swamp model method run <instance> patch --input registry=<registry[/namespace]>` builds, verifies, and pushes every image. The destination registry is the `registry` arg (or `globalArguments.registry`), so one instance retargets to a different registry per run. No workflow. Verify is foreknowledge-free (asserts no security updates remain pending on every platform), which fits a scheduled cadence; an optional per-image `expect` adds a version floor. Composes the pure logic of @hivemq/oci/image/patch and the buildx wrapper of @hivemq/docker; it is the only one of the three that drives buildx. Motivated by PLT-941 (openssl CVE-2026-45447): own the patch cadence instead of waiting on upstream base rebuilds.

Measure what a Docker host's disk is actually spent on, plan what can be freed without destroying a rollback target, and free it. The command people reach for is the wrong one: `docker image prune` — dangling or `-a` — never touches the BUILD CACHE, and on a host that builds its own images the build cache is usually most of the footprint. On the host this was written against it was 59.5GB of a 77GB reclaim, which no amount of image pruning would have recovered. Three behaviours are deliberate because each one corresponds to a way the obvious command does damage or lies. `docker image prune -a` removes every image no container references, which is precisely the set of previous versions a rollback needs; this model instead protects the newest `keepVersions` tags of each repository and removes specific image IDs, so reclaiming space does not quietly cost you the ability to go back. `docker builder prune -af` deletes the cache that makes the next build fast, and cache that is minutes old is the most valuable cache there is; pruning is therefore age-filtered via `--filter until=`, so a scheduled run takes cold layers and leaves the working set. And Docker reports sizes as rounded human strings where 1000 versus 1024 is a real 7% at terabyte scale, so parsing is explicit and unit-aware and the freed figure is measured by observing free space before and after rather than by summing estimates. Each method writes its own data instance — `usage`, `plan`, `reclaim` — so an expression always gets the schema it expects rather than whichever method ran last. `observe` and `plan` are read-only and safe to schedule at any frequency; `reclaim` is dry-run unless passed `apply: true`, and even then never removes an image that any container references, running or stopped. Host key checking is left ON by default — `StrictHostKeyChecking=no` is available but is not the default, because a model whose entire purpose is running destructive commands as a privileged user is the last place to accept an unverified host key.

Build, run, and push container images via Docker, Podman, or Apple

Auto-applier for docker image updates — pulls + restarts compose stacks with deny lists, cooling periods, and a per-run cap.

Render, validate, and remotely apply Caddy JSON reverse-proxy configuration using a containerized Caddy runtime.

Docker container discovery + autoheal across a Proxmox cluster — SSHes to each PVE node, runs `pct exec <vmid> docker ps` on every docker-tagged LXC; the autoheal method restarts unhealthy containers within deny-list/cooldown/cap guardrails.

Read the swamp version a host or container is running and report how far it has drifted behind the published channel. Read-only — it never updates, installs, or restarts anything; it tells you a newer build exists and stops there. Fills the gap `swamp update --check` leaves: that answers for the binary invoking it, on the platform invoking it, which is no help when the install you care about is a pinned binary inside a container on another host. `sync` records what a target reports about itself — its version and, via `uname`, the artifact platform it runs on. `drift` resolves the newest build published on a channel for THAT platform and reports status (`current`/`behind`/`ahead`) plus the lag in hours. Targets are reached three ways: the local binary, `docker exec` (optionally through a named docker context, so one host can check a container on another), or SSH with BatchMode so an unattended run fails fast instead of hanging on a password prompt. The channel is resolved by a single HEAD against the `stable` alias, reading the resolved version out of its website-redirect metadata — one request rather than the ~90 MB the archive weighs — and the same pass verifies the platform-specific archive is actually fetchable, which is the precondition for pinning a rebuild to it. Versions are compared numerically because the build ordinal in `YYYYMMDD.HHMMSS.N` is not zero-padded: as strings `20260808.001107.10` sorts below `...9`, so a string compare reports a target one build behind as up to date the day a tenth build ships. `hoursBehind` is derived from the timestamps embedded in each version and is documented as a lag, not a count of missed builds — swamp publishes no release list, so the builds in between cannot be enumerated and this extension does not pretend otherwise. An unreachable target, an unparseable version at either end, a channel alias that answers without its redirect header, and a resolved archive that 404s are all raised as errors rather than folded into a reassuring `current`.

Lifecycle management for a Colima VM (macOS container runtime, https://github.com/abiosoft/colima) via the local colima CLI: start and provision, stop, restart, delete, sync VM status, and exec commands inside the VM. One model instance targets one Colima profile.

Tracks a Docker Compose project's structure (services, volumes, networks) and flexible key/value configuration as swamp-managed data. Data-only — pair it with @keeb/docker/compose for actual lifecycle execution. Every parameter, service field, and volume/network option is validated against the official compose-spec JSON Schema before it's written, so typos and malformed values are rejected at write time rather than surfacing later as a broken `docker compose` run. Ships with a bundled schema snapshot so it works fully offline out of the box; run the updateSchema method on an instance to refresh it from the canonical compose-spec repository when you need a newer field.

Manage Docker Engine and Docker Compose lifecycle on remote hosts over SSH, including install, build, run, inspect, exec, and compose service operations.

Manage the X.509 certificate lifecycle (issue, renew, revoke, inspect) against a Smallstep step-ca certificate authority over the network — CA-agnostic, works with any reachable local or remote step-ca via its root fingerprint. Secondarily includes an optional model to stand up and tear down a local step-ca instance in Docker for development.

Keep :latest-tagged (and untagged) services in local or SSH-reachable docker compose projects up to date. Compares each running container's image digest against the registry (docker buildx imagetools) so already-current services are left untouched, then pulls and recreates only stale ones with a health-gate. Dry-run by default. Supports sudo-prefixed docker and per-host SSH config.

Management of an Arcane Docker instance via its REST API — GitOps sync setup, compose project lifecycle with validated mode-aware deploy, swarm stack deploy (render-validated, convergence-polled) + secret/config rotation, and volume/prune cleanup.

Portainer API wrapper — snapshot endpoints/containers/stacks across every docker host, and drive container actions (start/stop/restart/kill/pause/unpause) plus image pulls from swamp workflows.

Docker image update tracker — compares local image digests against the registry to surface available updates per container.

Local Docker image smoke testing for swamp: build image matrices, run containers, poll health checks, capture logs, and clean up.