Warning

Work in progress: no release yet. The supervisor (whr serve), the CLI, the web UI and the Apple Container and Claude Code adapters exist and are tested, mostly against fakes; the first end-to-end run of a real issue (#28) is next. Command names outside the stable set and parts of the architecture will still change. Do not use it to supervise real work yet. Documentation: https://wstein.github.io/workharbor/.

A self-hosted supervisor for AI coding agents: isolated workspaces, your approval for every push, one dashboard on every device. Agents work on repository issues independently in managed, isolated workspaces; you stay in the loop to answer questions, intervene, review and approve.

The command-line tool is whr.

Concept

• A supervisor with a dashboard, not an IDE. Tasks, runs, workspaces and environments are separate objects you watch and steer from the dashboard (web, phone) or the CLI; attaching or detaching an editor never interrupts the agent.
• Workspaces with named agents. A workspace is a folder with its own isolated environment; each named agent (<workspace>/<role>) works on its own branch there. A console environment gives you a shell next to them, without logging in to the host.
• Human in the loop. Agents raise decisions (questions, approvals, reviews); you answer them from your phone, the web app or the CLI.
• Isolated by default. First target is Apple Container on an Apple-silicon Mac mini: each workspace gets its own environment (a lightweight VM), reaching the internet only through an allowlist proxy, with short-lived, per-run forge credentials. The agents of one workspace share that environment; put agents that must not touch each other in separate workspaces. Other runtimes follow through adapters.
• Your agent, your login, within its terms. Claude Code first, with your own subscription or an API key. You sign in inside each environment; whr never handles a subscription login, and only you start runs (vendor terms).
• Approval boundaries are policy. Agents commit inside their environment; the host never runs git there. An agent's commits leave as a git bundle, are checked on the host against a supervisor-owned mirror of the repository, and are pushed only after you approve the exact commit ("Ready to push?"). Merge, tag, release and deploy stay with you, enforced by the forge adapter, not by prompts.
• One service layer. The whr CLI (over the JSON API) and the server-rendered web UI share the same service layer.

What goes wrong when agents run unsupervised

Each failure below has an answer in the design. Release 1 is still being built, so these are the intended behaviour, not a track record.

• Nothing stops a push. An agent can push its own work. Here an agent's commits leave as a bundle and go to the forge only after you approve the exact commit; merge, tag, release and deploy stay forbidden for agents (approval boundaries, security).
• No isolation. An agent runs with your host's files and network. Here each workspace has its own environment, and its agents reach the internet only through an allowlist proxy (isolated by default).
• Secrets are within reach. Long-lived tokens end up where an agent can read them. Here forge credentials are short-lived and per run, and whr never handles a subscription login (vendor terms).
• No way to follow or stop a run. Here runs, decisions and events are visible in the dashboard and the CLI, and you can steer or stop a run from either (whr logs, whr say, daily use).
• One login shared by many agents. Here the agents of one workspace share that workspace's sign-in (you sign in once per environment), and only you start runs; several sessions on one sign-in is an open question, D42 and #82 (vendor terms).

What you need

• An Apple-silicon Mac mini (or Mac) running macOS with Apple Container, the first runtime. Release 1 supports no other host.
• A GitHub App for the repositories the agents work on: whr github app create makes it from a manifest.
• An agent login: a Claude subscription, signed in inside the environment and never given to whr, or an API key, which whr keeps in a 0600 file.
• Go, only to build from source.

The manual walks through the host, the App and the first run. It is a draft until the first release.

CLI (provisional)

whr serve                      # the supervisor: JSON API, web app, reconciler
whr run <issue-url> --agent <workspace>/<role>
whr ls
whr logs <task> -f
whr say <task> "use the existing retry helper"
whr inbox
whr approve <decision>
whr answer <decision> <option>

These are the stable commands of the first slice (design D37); they exist but have not run against a release yet. Others (whr ws, whr agent, whr console, whr setup, whr doctor, …) are provisional; see the manual.

Build

make build         # bin/whr
make install       # whr, whr-shim and whr-proxy from a clean commit on origin/main

The dogfood host installs a draft release instead (make install-release VERSION=<tag>); from v0.1.0 on, brew install wstein/tap/whr.

Setting up the host is in the manual; installing, upgrading and releasing are on its install page.

Stack

Go, a single static binary, SQLite, and a server-rendered web UI (templ, htmx, SSE).

Status and roadmap

Building release 1, dogfood first: workharbor develops workharbor as soon as it can run one issue end to end (D34). The plan is tracked in GitHub milestones:

1. Dogfood: the smallest set that runs a real workharbor issue through whr
2. M0 Decisions (closed): the design decisions and spike follow-ups that came before release 1; new decisions are tracked in the issue that needs them
3. R1 Slice: a CLI-only vertical slice, whr run <issue-url> to an opened pull request
4. R1 Complete: the rest of release 1, including the web app for phone and tablet
5. Later: medium and long term, such as API-key mode as a full peer (D41)

See all milestones, open issues and the delivery plan in the design.

Contributing

Contributions are welcome, especially design reviews and the open spikes. Please read CONTRIBUTING.md and the Code of Conduct. Report security problems privately as described in SECURITY.md.

License

EUPL-1.2