Project-first
Every project has its own keeper agent, files, and changelog. Notebook projects live in your data repo; repo-backed projects clone an external git repo as the agent’s working directory — and a notebook can be promoted to one later.
Paddock
Your Claude Code agents, hosted and organized by project — persistent, resumable sessions with a web UI, from your desk or your phone.
What is Paddock?
Section titled “What is Paddock?”Paddock is a project-first launchpad for herdctl. It turns Claude Code into something you run on a server and reach from a browser: long-lived agents, one per project, whose chats persist and resume — instead of a laptop full of terminal tabs you can’t get back to from your phone.
A project is just a directory. Each one gets a herdctl keeper agent whose working directory is that project, and the chats you see in the UI are that agent’s Claude Code sessions — persisted on disk and resumable across reloads, reconnects, and devices.
And a chat isn’t the only way work starts. Keepers run on a schedule, react to events, and can be driven by an external MCP client — so a project keeps moving while you’re asleep, and you read the transcript in the morning.
Paddock isn’t just for software engineers. A project can be a codebase, but it
can just as easily be a research notebook, a writing desk, or a home-ops runbook —
anything you’d want a capable, always-available agent to work on. It shines when you
run it on an always-on machine and give its agents the tools they need (a scoped
GitHub token, ffmpeg, whatever your work calls for). See
Who Paddock is for.
Persistent, resumable chats
Server-hosted sessions survive reloads, reconnects, and devices. Fork, queue-while-streaming, stop, search, pin, and archive are built in, and a keeper that gets stuck is nudged back to work.
Real tool use, streamed live
Replies stream token by token. File writes, commands, and nested sub-agents render as live cards as they run, with per-chat cost and a context meter you can read at any point in the transcript. Send it files and images, too.
Work that starts itself
One triggers model covers both halves of unattended work: cron schedules and event hooks that fire a scoped agent when something happens. Run history shows what ran while you were away.
Yours to host
Two official images — a lean base and a devbox with the full coding-agent toolbox — plus ready-made Docker, Proxmox, Kubernetes and reverse-proxy-auth recipes. Bring your own authentication; it ships with none.
Open at both ends
A thin project layer over the herdctl FleetManager, so anything the fleet
engine does Paddock can wire in. On the other side, a credential-gated
management API at /mcp lets an outside MCP client drive it — read-only
until you say otherwise.
Start here
Section titled “Start here” Getting started Run Paddock with Docker or from source.
What's new What landed recently, release by release.
Working in chats Streaming, queueing, forking, stopping — the day-to-day.
Deploying Paddock The recommended always-on, low-power setup.
Securing Paddock Put authentication in front — read before exposing it.
Concepts Projects, keeper vs scratch agents, chats-as-sessions, triggers, the sweeper.
Configuration Every PADDOCK_* environment variable, with defaults.
Architecture Storage model, WebSocket flow, MCP injection, auth.