paddock

module

v0.5.2 Latest Latest Go to latest Published: May 2, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/tjorri/paddock

Links

Open Source Insights

README ¶

Paddock

Run AI agent harnesses as first-class Kubernetes workloads, with the safety rails built in.

Paddock is an open-source, Kubernetes-native platform for running headless AI agent harnesses — Claude Code, Codex CLI, OpenCode, Pi, or anything else you can put in a container — as templated, sandboxed, observable batch workloads. A capability-scoped broker issues short-lived credentials and a per-run egress proxy MITMs TLS so the agent never sees upstream API keys.

Status: pre-1.0. Expect breaking changes between minor versions until v1.0; pin to a tagged release for stability.

What's in the box

Five CRDs (HarnessTemplate / ClusterHarnessTemplate, HarnessRun, Workspace, BrokerPolicy, AuditEvent), a control plane (controller + admission webhooks + capability-scoped broker), and per-run sidecars (egress proxy + adapter + collector + a transparent-mode iptables-init). Reference harnesses: paddock-echo (deterministic CI fixture) and Claude Code (real-agent demo). See docs/concepts/components.md for the full inventory.

Documentation

docs/ is the audience-routed entry point. Pick the path that matches what you are doing:

Evaluating Paddock — docs/getting-started/quickstart.md walks through a Kind cluster end-to-end in ~10 minutes.
Installing into a real cluster — docs/getting-started/installation.md covers Helm OCI, manifest install, and Cosign verification.
Understanding the model — docs/concepts/, starting with architecture.md (CRD relationships, Pod composition, admission) and components.md.
Trust review — docs/security/threat-model.md.
Operator recipes — docs/guides/ (provider setup, delivery modes, allowlist bootstrap).
Reference — docs/reference/ (CRD + CLI; autogeneration in progress).

For the deepest internal reading: VISION.md (product north star) and docs/internal/specs/ (numbered implementation specs).

Contributing

See CONTRIBUTING.md for dev setup, commit conventions, and the ADR process. Architecture decisions live at docs/contributing/adr/.

License

Apache 2.0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
api
v1alpha1 Package v1alpha1 contains API Schema definitions for the paddock v1alpha1 API group.	Package v1alpha1 contains API Schema definitions for the paddock v1alpha1 API group.
cmd
adapter-claude-code command Command adapter-claude-code is the event adapter sidecar for the paddock-claude-code harness.	Command adapter-claude-code is the event adapter sidecar for the paddock-claude-code harness.
adapter-echo command Command adapter-echo is the event adapter sidecar for the paddock-echo harness.	Command adapter-echo is the event adapter sidecar for the paddock-echo harness.
broker command Command broker is the entrypoint for the paddock-broker Deployment.	Command broker is the entrypoint for the paddock-broker Deployment.
collector command Command collector is the Paddock collector sidecar.	Command collector is the Paddock collector sidecar.
iptables-init command Command iptables-init installs per-pod NAT rules that redirect outbound TCP traffic on ports 80 and 443 to the paddock-proxy sidecar listening on :15001.	Command iptables-init installs per-pod NAT rules that redirect outbound TCP traffic on ports 80 and 443 to the paddock-proxy sidecar listening on :15001.
kubectl-paddock command kubectl-paddock is the kubectl plugin for operating Paddock.	kubectl-paddock is the kubectl plugin for operating Paddock.
paddock-tui command paddock-tui is the interactive multi-session TUI for Paddock.	paddock-tui is the interactive multi-session TUI for Paddock.
proxy command Command proxy is the entrypoint for the paddock-proxy sidecar.	Command proxy is the entrypoint for the paddock-proxy sidecar.
images
evil-echo command evil-echo — hostile harness for adversarial Paddock E2E tests.	evil-echo — hostile harness for adversarial Paddock E2E tests.
internal
auditing Package auditing is the single source of truth for AuditEvent emission across broker, proxy, webhook, and controller.	Package auditing is the single source of truth for AuditEvent emission across broker, proxy, webhook, and controller.
broker Package broker is the runtime for the paddock-broker Deployment.	Package broker is the runtime for the paddock-broker Deployment.
broker/api Package api defines the wire shape of the broker's HTTP/JSON API.	Package api defines the wire shape of the broker's HTTP/JSON API.
broker/providers Package providers implements the broker's pluggable credential backends.	Package providers implements the broker's pluggable credential backends.
brokerclient Package brokerclient is the shared HTTPS plumbing for the controller's and the proxy's broker clients.	Package brokerclient is the shared HTTPS plumbing for the controller's and the proxy's broker clients.
brokerclient/brokerclienttest Package brokerclienttest is a test-only support package: it lets out-of-package tests in internal/controller and internal/proxy construct a brokerclient.Client without going through the F-29 canonical-endpoint validator.	Package brokerclienttest is a test-only support package: it lets out-of-package tests in internal/controller and internal/proxy construct a brokerclient.Client without going through the F-29 canonical-endpoint validator.
cli Package cli implements the kubectl-paddock plugin.	Package cli implements the kubectl-paddock plugin.
controller Package controller implements the Paddock reconcilers.	Package controller implements the Paddock reconcilers.
controller/testutil Package testutil holds shared fakes and helpers for tests that exercise the controller package.	Package testutil holds shared fakes and helpers for tests that exercise the controller package.
paddocktui/app Package app holds the Bubble Tea Model, Update, View, and message types for the paddock-tui interactive UI.	Package app holds the Bubble Tea Model, Update, View, and message types for the paddock-tui interactive UI.
paddocktui/broker Package broker is the TUI-private HTTP+WebSocket client for the paddock-broker.	Package broker is the TUI-private HTTP+WebSocket client for the paddock-broker.
paddocktui/cmd Package cmd implements the paddock-tui binary's cobra command tree.	Package cmd implements the paddock-tui binary's cobra command tree.
paddocktui/events Package events provides deduplication and polling helpers for HarnessRun.status.recentEvents, used by the paddock-tui and related CLI commands.	Package events provides deduplication and polling helpers for HarnessRun.status.recentEvents, used by the paddock-tui and related CLI commands.
paddocktui/runs Package runs wraps HarnessRun create/watch/cancel operations from the paddock-tui's perspective.	Package runs wraps HarnessRun create/watch/cancel operations from the paddock-tui's perspective.
paddocktui/session Package session contains client-side primitives for treating a labeled Workspace as a paddock-tui session: list/create/end/watch and template-default annotations.	Package session contains client-side primitives for treating a labeled Workspace as a paddock-tui session: list/create/end/watch and template-default annotations.
paddocktui/ui Package ui contains View functions and Lipgloss styles for the TUI.	Package ui contains View functions and Lipgloss styles for the TUI.
policy Package policy implements the shared admission and runtime capability logic from ADR-0014.	Package policy implements the shared admission and runtime capability logic from ADR-0014.
proxy Package proxy implements the per-run egress proxy sidecar for Paddock v0.3.	Package proxy implements the per-run egress proxy sidecar for Paddock v0.3.
webhook/v1alpha1
test
utils