werkdock/AGENTS.md

werkdock Agent Instructions

Project

werkdock is a docker-like sandbox CLI over bwrap, with filesystem isolation only; see README.md. Werkator runs its CI builds and werkrevisor's reviews in werkdock sandboxes on mih09. docs/werkdock.werkbaum holds the plan, docs/rfcs/ the decisions.

Build and Test

go test ./...                              # all tests; sandbox integration tests skip without bwrap/userns
go vet ./... && gofmt -l .                 # quality gates (gofmt must print nothing)
CGO_ENABLED=0 go build -o dist/werkdock .  # one static linux binary
tools/check-licenses                       # licenses of the dependencies against tools/allowed-licenses.txt; each build
go run ./tools/vulncheck -base origin/main # only the called vulnerabilities this branch brings; each PR
go run ./tools/vulncheck                   # all called vulnerabilities; main each night

The checks load govulncheck and go-licenses by go run at a pinned version; neither becomes a dependency of the module. Their levels come from docs/risk-analysis.md, criticality high. An exception from a vulnerability goes into tools/vulnerability-exceptions.txt, with its reason.

Hard Invariants

• Filesystem isolation only: network, uid, /proc, /dev and /tmp come from the host by contract. This is what makes werkdock work without root on a Hostsharing Managed Webspace.
• Go, one static binary, standard library only (RFC 0001); a third-party dependency needs an RFC.
• Verbs and flags follow docker (RFC 0002); where docker and podman differ, werkdock follows podman. A docker flag or API endpoint that werkdock does not support fails with the reason, never silently.
• The Docker Engine API serves only endpoints measured from a real client, listed in docs/testcontainers-api.md; every other one answers 501 with the reason.
• A quirk is measured knowledge about one image version; an image that no longer matches it is refused, not guessed at.
• No imports from Werkator code and no coupling to the Werkator build; Werkator consumes the binary through PATH.

Workflow

Follow docs/agentic-workflow.md, the workflow of all Werk repositories: roles, steps of a PR, review rounds, PR documents, the plan, versions and the writing style. In addition, for werkdock:

• Documents are in English.
• The version stands in internal/cli/cli.go (what werkdock version prints). Each PR raises it and adds a section with that version and the merge date to CHANGELOG.md: what changed, what stays compatible, and what a consumer, Werkator first, must adapt. A change that consumers do not notice gets a section marked as internal.
• A decision larger than one PR is an RFC under docs/rfcs/.
• A merge to main is a release; the CI deploys nothing. The rollout to mih09 is manual: the new binary to ~/.werkator/bin/werkdock of the account mih09-werkator, then a restart of the systemd user units werkdock-api-*.service, which otherwise keep serving the old code.