Agent Orchestrator
A deterministic, self-hosted approach to agentic engineering.
AI coding agents build in isolated containers. A separate agent reviews the result. Every step is tracked and reported on for human observation.
Designed and built with AI agents
I built Agent Orchestrator by designing the core architecture collaboratively with an AI agent harness. I challenged design decisions to ensure the product would be capable of evolving and incorporating the future features I had planned.
When the design was completed, I directed the agent to break the design down into actionable tasks and to progressively implement the system. This itself was the development workflow that I wanted the Orchestrator to help me deliver.
Once the core orchestration loop was implemented, I was able to use the system itself to implement the remaining features. This allowed me to test the system while developing further improvements.
Inside the tool
The design decisions behind it
Free, self-hosted, no vendor lock-in
Four agent harnesses: Claude Code, the Claude Agent SDK, OpenCode, and pi. Across eight providers. Forgejo for version control. Free, self-hosted end to end.
Safe and easy to operate
Sandboxed environments for agentic development. The system recovers from unplanned outages, which are common for self-hosted systems.
Human-led design, agentic implementation
MCP server for handing off tasks. Collaboratively develop designs with an AI agent, send tasks off to the Orchestrator for implementation, or create them via the UI.
Observability, optional human in the loop
Development work and review comments are exposed in PRs. The Orchestrator exposes logs for active agents. Human review and merge can be made mandatory.
How it fits together
- A containerised Node.js control plane coordinates task execution.
- Forgejo provides version control and issue tracking.
- Disposable containerised sandboxes host the AI agent harnesses.
- A custom web interface and MCP clients are used for task creation, monitoring, and configuration.
Sharing only network protocols, the components make no assumption about where they run: one machine, or the Git server, control plane, and sandbox pool split across several, with no change to the design.
The task lifecycle
- Queue. An issue is labelled for work from the dashboard or over MCP. Dependencies declared in its body hold it back until the issues they name close.
- Prepare. The control plane claims the issue, fetches the repo, creates a branch, and assembles the prompt from the issue and any prior review feedback.
- Implement. A dev agent actions the task, following repo-specific guidelines, self-reviews, commits, and pushes.
- Review. The Orchestrator creates a pull request and a review agent reads the full diff, runs the tests, and returns a structured verdict with file-and-line feedback.
- Rework. A fresh dev container starts with the review feedback in its prompt, bounded by an attempt budget to prevent infinite loops.
- Merge. On approval, the control plane re-checks mergeability, merges with the repo's strategy, closes the issue, and posts the outcome.
Every transition is posted back to the issue as a comment: the audit trail for unattended work lives in the Git server, not inside the Orchestrator.
Where a human steps in
Autonomy is the default but not a requirement. Configurable per repository, or per task, the code review and the decision to merge can be deferred to a human.
- Enforce human review
- A human-review label stops the workflow once the pull request is open, leaving it for a human to review.
- Enforce human merge
- A human-merge label runs the full implement-and-review cycle, then leaves the pull request open pending final approval by a human.
- Escalate stalled tasks
- An unclear verdict, or a task that keeps failing, parks the task for human review instead of merging or discarding the work.
- Control work in flight
- Pausing the queue, reordering tasks, changing the implementer and reviewer agent profiles, raising attempt budgets, or cancelling tasks are just some of the ways a human operator can influence the workflow.
- Reset to start fresh
- Any finished-but-unmerged task resets in one action: branch, pull request, and workspace deleted, attempt counters cleared, issue returned to unqueued.
What it demonstrates
- Distributed-systems thinking: an explicit state machine, crash recovery, resource-aware scheduling.
- Security: container isolation, scoped credentials, OAuth 2.1.
- Product design: a live dashboard and a one-command developer plugin.
All in a platform kept portable and free of vendor lock-in by its harness- and provider-agnostic core, and delivered by directing AI agents rather than writing every line by hand.
← Back to all projects