Keelworks specification

Design

No-Docker build controller in the clearedstack namespace that spawns ephemeral ko and rootless BuildKit Jobs on push, runs golden tests, signs digests with cosign, and updates app.yaml.

J.4.62 min readLast revised November 2026

Status: Design. A specification. It describes how the component is meant to work, not something you can use on this site today. What the labels mean.

Registry entry

Tests, builds and signs an image for every change.

Formerly: cs-runner, then Slipway
Namespace: clearedstack
Repository: keelworks
Container image: lazarette.clearedstack.svc.cluster.local:5000/keelworks
Depends on: Plainforge, Lazarette
Depended on by: Nothing else in the platform
Boundaries: Receives push notifications from Plainforge
Pushes signed images to Lazarette
Writes the new image digest back to Plainforge

From the naming registry, which is the one place this component’s name is written down.

On this page

Overview & Role
Runtime & Resource Budget
Interfaces & Data Contracts
Sub-Tools & Failure Modes
Security & Clean-Room Boundaries
Related pages

Overview & Role#

Keelworks (v0.1.0-draft, owned by the Keelworks repository) is a lightweight MIT Go control-plane service running in the clearedstack namespace. It replaces traditional Docker-based CI runners with an event-driven, daemonless build controller.

When Plainforge receives a commit on main or a new tag, Keelworks spawns an ephemeral Kubernetes Job pod to run the repository's deterministic golden fixture tests, compile an OCI image using ko (for Go services and workers) or rootless BuildKit (for web apps like Conn), sign the resulting digest with cosign, push it to Lazarette, and commit the new immutable digest back to app.yaml in Plainforge.

Runtime & Resource Budget#

Property	Value
Service / Repo	Keelworks (`keelworks`)
Namespace	`clearedstack` (`control-plane`)
Version	`v0.1.0-draft`
RAM Budget (Requested)	`32 MiB` (controller pod; build `Job` pods run ephemerally)
Priority Class	Standard / Low for ephemeral build `Job` pods (preempted before control-plane services under memory pressure)
Builders	`ko` (Go services & workers) and rootless BuildKit (Conn)
Sub-Tools	None (`[]`)

Interfaces & Data Contracts#

Keelworks coordinates four internal control-plane interfaces:

Webhook Intake (Plainforge -> Keelworks): Receives cluster-private push and tag webhooks from Plainforge. Commits containing [skip-ci] in the commit message are ignored to prevent recursive build loops.
Ephemeral Job Orchestration (Kubernetes API): Spawns short-lived Job pods in clearedstack with the appropriate builder:
- ko: Compiles Go binaries (Plainforge, Lazarette, Keelworks, Shipkeeper, Muster, and Trawl through Bellbuoy) directly into minimal OCI images with zero Dockerfile or Docker daemon.
- Rootless BuildKit: Builds multi-layer container images for Next.js web workloads (Conn) inside an unprivileged, rootless pod.
Test, Sign & Push (Job -> Lazarette): Executes golden fixture tests before building. Passing builds are signed with cosign and pushed by sha256 digest to Lazarette.
Manifest Pinning (Keelworks -> Plainforge): Updates the pinned image digest in app.yaml inside Plainforge with a [skip-ci] commit so Shipkeeper can reconcile the new release.

Sub-Tools & Failure Modes#

Keelworks is a control-plane build controller and does not host tools/<case>/ deterministic sub-tools (subTools: []).

Failure Mode	Trigger	System Behavior & Recovery
Golden test failure	A commit breaks a deterministic fixture or unit test	The build `Job` aborts before packaging or pushing; broken images never enter Lazarette.
Build or push timeout (`E_TIMEOUT`)	Slow dependency fetch or registry stall	The `Job` terminates cleanly and reports `E_TIMEOUT`; no partial digest is written to `app.yaml`.
`cosign` signing failure	Missing or invalid signing key material	Image push is blocked or left unsigned; Shipkeeper refuses to roll out unsigned digests.
Memory preemption	Node memory tightens during a build `Job`	Low PriorityClass allows `k3s` to preempt ephemeral build `Job`s first while protecting Logbook, Muster, and Shipkeeper; deterministic builds can be safely retried.
Recursive CI loop	Keelworks committing `app.yaml` back to Plainforge	Prevented deterministically by tagging `app.yaml` commits with `[skip-ci]`.

Security & Clean-Room Boundaries#

Zero Docker daemon: No Docker socket (/var/run/docker.sock), privileged containers, or root-level build daemons exist anywhere on the host or inside build Job pods.
Rootless & unprivileged: Both the Keelworks controller and its spawned ko / rootless BuildKit Jobs run as non-root users with dropped Linux capabilities and no privilege escalation.
Cluster-private only: Keelworks has no public Ingress and accepts webhooks exclusively from Plainforge under default-deny NetworkPolicy rules.
Supply-chain integrity: Every published image is tested against golden fixtures and cryptographically signed with cosign before app.yaml is updated.

Found a mistake, or something that has gone out of date? Open an issue or write to [email protected]. This page is a text file you can read and correct: Source of this page.