Skip to content
Documentation
Design

Design

CLI: whr · Status: Revised design, updated 2 October 2026 · Building release 1, dogfood first (D34): what is below is implemented and tested, mostly against fakes, and the first end-to-end run of a real issue on the reference Mac mini (#28, after #73) is next. Spikes are measured with committed scripts and published on the spike pages. Results are marked in the sections they affect.

StatusWhatWhere
DecidedD1 to D49 and D51 (D50 is reserved, #112)§3; new decisions are tracked in the issue that needs them (the M0 Decisions milestone is closed)
ImplementedThe domain (state machines, Decisions, the aggregate and its guards), the policy table, the SQLite store with redaction at ingest, the service layer and reconciler, hostgit (checkout checks, the repository cache, prepare and push, the editor copy), the runtime and agent contracts with their conformance suites, the Apple Container adapter with the egress proxy sidecar (ports 443 and 80, public addresses only, exec environment through a 0600 env file), the tool store (https only, size cap), the config file (secrets outside every root, an API key only, D40) and make install (from a commit on origin/main), push after approval with follow-up rounds as fast-forwards, the Claude Code adapter (dontAsk with an allowlist, or manual with host approvals over the stdio control channel), ntfy notifications, whr version, the whr-shim launcher, and the design-drift test; whr serve with the JSON API on a host-only socket, the CLI (D37), the web UI with passkey sign-in and step-up, previews and the usage dashboard, workspaces with named agents and the bundle export, the console with SSH certificates, workflow presets (D47), the setup wizard (D46), the launchd job, the board mirror, devcontainer environments with egress requests, release installs from drafts and the Homebrew tap workflow, and fuzz tests of the untrusted-input parsersPackages under internal/ and cmd/; what remains for the first dogfood run is the Dogfood milestone, the rest of release 1 the R1 Slice and R1 Complete milestones
SpikedAgent contract (Claude Code, Codex CLI, Antigravity); Apple Container; host cancel with whr-shim; approvals over stdio; planted Claude Code config; host reachability; bind mount against volume, and a volume over a bind mountIssues #1, #2, #10, #7, #68, #69, #40 and #80; the spike pages; results in §4.2, §4.4, §5.1 to §5.3, §5.6, §7
Open spikesSigning in to the agent inside an environment (D40); what guests reach on the host with pf rulesIssues #82, #69
PlannedThe release 1 slice and the rest of release 1§13; R1 Slice and R1 Complete milestones

Revision of the original discussion summary (agent-work-supervisor-summary.md) after a four-role team review (architecture, security, product/CLI, feasibility/ops). Review ratings are value/effort out of 10. Claims about Apple Container that spike #2 measured are stated as measured in §4.4, §5.1, §5.3, §5.6, §7 and §12. Claims about Socktainer, Coder and Portainer, and anything marked unverified, still come from the original sources and are unverified until the remaining spikes in §12 are done.

The design is split by topic. Section numbers (§) are the same on every page, so a reference such as §4.5 finds its page here:

PageSections
This page§1 Goal, §2 Requirements, §14 Review log, §15 References
Decisions§3 Key decisions (D1 onwards)
Domain model§4 State machines, Decisions, lifecycle, persistence, topics and cleanup before push
Architecture§5 Adapters, reconciler, events, plugins, tool store, usage; §8 Resources
Security§6 Policy and autonomy, §7 Security
Interfaces§9 CLI, scripting contract, web UI, notifications, onboarding, mobile clients; §10 Forge, CI and identity
Roadmap§11 Existing platforms, §12 Open decisions and spikes, §13 Delivery

1. Goal

A self-hosted service in which AI coding agents carry out project work independently while one developer acts as human-in-the-loop (HitL): intervening, answering questions, reviewing and approving.

  • Agents work repository issues, modify code, run tests and commit in their own checkouts. After a cleanup step and the developer’s approval the supervisor pushes the branch and opens or updates the PR (§4.5).
  • Usage is a live coding assistant, not an automation pipeline: the developer chats with an agent about the work, then detaches while it works for 15 to 60 minutes or longer, and returns when it needs them. A personal tool with one developer and a handful of concurrent sessions.
  • The developer attaches via chat, SSH or an editor temporarily. Disconnecting never interrupts the agent.
  • Web UI and whr CLI are two front ends over one service layer: the CLI calls the JSON API, the web UI is server-rendered HTML (see D8).
  • First host: Apple-silicon Mac mini on Apple Container, recommended M6 with 32 GB memory and 512 GB storage (D32). Other runtimes later via adapters.

The central concept is an agent task supervisor with managed workspaces, not an editor-centred dev environment.

Positioning. workharbor is a self-hosted, agent-agnostic remote for coding agents. From a phone or a browser the developer starts a task, chats with the agent, watches progress, answers its questions and pauses or cancels it, with Claude Code, Codex CLI and later other agents behind one interface (§5.2). It runs on the developer’s own machine with their existing agent logins, so there is no hosted service in the middle. Hosted remote offerings from the agent vendors cover one vendor each; where they fall short for a given agent (for example a missing mobile or remote client) is unverified and is checked in the §12 spike. The boundary stays: agents never merge, tag, release or deploy (§6).

2. Requirements

AreaRequirement
DeploymentOn-premises, one developer
HardwareApple-silicon Mac mini: M6 with 32 GB memory and 512 GB storage recommended; on a budget 16 GB, with 512 GB or with 256 GB plus an external SSD; 24 GB / 512 GB in between (D32, §8)
RuntimeApple Container (per-container VM isolation); Firecracker microVMs on Linux in the medium term (#140); Proxmox VE and VMware vSphere, and a Windows host with Hyper-V VMs, in the long term (#140); Docker/Podman and other microVMs later; not VirtualBox or WSL2 as runtimes (§13)
Capacity4 concurrent instances realistic, 8 a stretch goal (see §8)
OverheadLight operational and resource cost
AccessVPN, temporary SSH, VS Code / JetBrains via SSH; code-server optional and later
ForgesGitea, Forgejo, Codeberg, GitLab, GitHub (release 1: GitHub, D15)
CIDrone medium/long term, behind an adapter
AuthOAuth for the five forges (release 1: a static access token and passkeys, §9.5, D45; the forge through a GitHub App, D15)

14. Review log

Reviewers disagreed on three points; the resolutions adopted here:

  • Forge handoff: manual compare-URL handoff (product) vs one forge, no half-state (architect). Adopted: one forge, no half-state; since D15 that forge is GitHub through a GitHub App, not a PAT.
  • Web UI: defer entirely (ops) vs minimal inbox (product, architect). Adopted then: a minimal read-mostly UI with inbox, since decisions are answered there. Since superseded by the remote-control scope of §9.3 (D8, D12).
  • UI stack (D8): templ + htmx (option 1 of 7 weighed) over Svelte, Preact, React and others. The cost is that the UI does not consume the JSON API directly; the shared service layer keeps the two front ends consistent.

Skipped for now: separate identity service, Kubernetes, multi-host placement, Portainer/Coder UI integration.

15. References

Carried over from the original summary; compatibility claims require testing against pinned versions.