SFreedom Logo
Developer toolingArchitecture record

Self-Hosted AI Agent Orchestrator

The tool solves a specific annoyance: AI coding assistants are per-repository, single-shot and stateless, so instructions get copy-pasted into every project and a failed run has to be restarted by hand. This orchestrator inverts that. A control plane owns tasks and workflow state, workers claim and execute steps, and agent profiles plus instruction sets are stored centrally and overlaid onto a repository at run time — so no project needs its own committed agent config.

53
Go files
across 15 packages
3
Binaries
cli, control plane, worker
4
Workflow steps
plan → work → verify → retry
15
Subsystems
agent, api, workflow, storage…
Repository shape

Go module with three binaries and fifteen internal packages

How this is presented

Documented as an architecture record. Self-hosted developer tooling is better explained by its control flow than by a hosted demo.

How a request becomes verified work

The control plane never executes anything itself. Watch how state and execution stay on opposite sides of the boundary.

CLIClient surface

Where a developer submits a request and inspects progress.

Client surfaceServiceData storeWorker / jobExternal
Plan, work, verify, retry

The full workflow for a single request.

Highlights

Separates the control plane from execution, so a crashed worker loses a step rather than the whole task.
Agent profiles and instruction sets live centrally and are overlaid per repository — no per-project agent config to maintain.
Workflow includes an explicit verify step, so 'the agent said it was done' is not the completion criterion.
Retry is part of the workflow rather than something a human does manually.
Provider abstraction for browser automation, so the backing implementation can be swapped without touching workflow code.
Persistent task state in SQLite, keeping the whole thing self-hosted with no external dependencies.

Control plane, workers, and overlays

Three moving parts: an authoritative control plane holding tasks and state, workers that claim and execute steps against local AI CLIs, and an overlay system that injects the right context into a repository without committing anything to it.

CLI

The user-facing binary for submitting and inspecting work.

  • Single entrypoint that fronts both the control plane and worker binaries.
  • Separate binaries remain available for focused development.

Control plane

Owns tasks, workflow state, project permissions and session records.

  • HTTP API with SQLite persistence — authoritative and self-contained.
  • Resolves which workflow and which agent profile a request should use.

Worker runtime

Claims tasks and executes workflow steps against local AI CLI tools.

  • Claim-based, so multiple workers can run without coordinating manually.
  • Rate limiting keeps CLI invocations inside provider limits.

Profiles and overlays

Shared agent instructions applied per repository at run time.

  • Central storage means one edit updates every project.
  • Repository overlays add context without forcing config files into the repo.

Binaries and internal packages

Three binaries over fifteen packages. The split between control-plane packages and worker packages is what lets a crashed worker lose a step rather than a task. 18 units across 4 groups.

Binaries

3
saosao-controlsao-worker

Control plane

6
controlplaneapidaemonstoragemodelconfig

Execution

6
workerworkflowagentsessionratelimittemplating

Integrations

3
browserticketingobsidian

Stack by layer

Entrypoint
Unified CLI binaryControl-plane binaryWorker binary
Control plane
HTTP APISQLite persistenceTask modelSession tracking
Execution
Worker runtimeWorkflow engineRate limitingTemplating
Integrations
Browser provider abstractionTicketingNote-store sync

Delivered work

Control plane and CLI

  • Unified CLI fronting the control-plane and worker binaries.
  • HTTP API with SQLite persistence for tasks, sessions and permissions.
  • Project permission resolution and workflow configuration.

Execution and context

  • Claim-based worker runtime executing multi-step workflows.
  • Plan, work, verify and retry steps with persisted position.
  • Central agent profiles with per-repository overlays.
  • Rate limiting, templating, ticketing and browser provider abstraction.

Modules and demo strategy

Workflow engine

Turns a request into a verified result.

  • Verification is a first-class step, not an afterthought.
  • Retry carries the failure forward as context.

Overlay system

Shared instructions without per-repo config files.

  • One central edit propagates to every project.
  • Keeps working repositories clean of tooling metadata.

Control/execution split

Makes crashes cheap.

  • State is authoritative and durable; execution is disposable.
  • Any worker can resume any task.

Frontend documentation format

How this project is presented

Control flow shown as an interactive walkthrough.
The control/execution split explained, since it is the load-bearing decision.
Verified package and file counts.