Reference architecture · v1
Autonomous engineering, on rails you already trust.¶
Agents do sandboxed work on the AGX Orin. GitHub is the substrate — for tracking, review, CI/CD, and release. You review real artifacts, not chat buttons. And it's one pattern, reused for every project.
The execution engine is Mezmo AURA (open-source, running natively on the AGX) — but AURA is a component. This document describes the system built around it: how blanny.org turns an issue into a reviewed, tested, released change, autonomously, using the same GitHub machinery a professional team already relies on.
The pattern in four tenets¶
GitHub is the record¶
Issues, board, PRs, Actions, Pages, Releases — not a bespoke queue or a state file on disk.
Agents are workers¶
Triggered by GitHub events, they do sandboxed work and report back into GitHub.
Review real artifacts¶
A PR with CI checks and a live preview build. Approval is a merge — never a Telegram tap.
One template, many projects¶
A template repo ships the whole machine; a new project inherits it on day one.
The stack¶
GitHub holds the work and the gates. The AGX is a self-hosted runner where agents and CI actually execute — on the real toolchain, with the local models free of charge. Everything routes through one OpenAI-compatible gateway to a local or frontier model.
The loop¶
This cycle runs for every unit of work, and it's identical across projects. The human touchpoints are the issue (what to do) and the PR (was it done right) — both native GitHub surfaces.
Milestone exit-criteria — builds, test output, visuals, audio — are all reviewed in the PR: CI runs
the headless build and smoke tests as required checks, and the web export deploys to a per-PR Pages
preview you can actually play, see, and hear before you merge. A request changes review re-triggers
the agent to revise.
Inside an agent team¶
The team is the part of the engine that carries over unchanged. A tool-less planner drafts the approach; an orchestrated executor does the work, farming subtasks across local and frontier models; a lean reporter turns the executor's prose into a structured status the loop can act on.
What the pipeline runs by default
Today's loop uses Aider as the coding agent — one fast, model-agnostic worker driving the local
LiteLLM gateway (Kimi / Qwen / DeepSeek, no Claude). The orchestrated team above is the heavier
path, available via team_create when a task genuinely needs planning and farming across models.
Known cost (the orchestrated path)
Orchestration isn't free: even a trivial coordinator round-trip is ~20–45s, so a real multi-tool step runs minutes, not seconds. That's acceptable because the work is async and PR-gated — you review outcomes, not a live grind. Where speed matters more than a committee, a team drops to a single-agent executor.
The template¶
A new project isn't wired by hand — it's created from a template repo that already carries the whole machine. Onboarding is "instantiate, then point it at the docs."
| Ships in the template | Purpose |
|---|---|
.github/workflows/ci.yml |
Headless build + smoke tests on every PR — the required check |
.github/workflows/preview.yml |
Web export → Pages preview URL, commented on the PR |
.github/workflows/release.yml |
Build + publish a Release on merge / tag |
.github/workflows/agent.yml |
On agent:go label / /agent comment → run the agent on the AGX runner |
| Labels + issue templates | agent:go, needs-review, blocked, area tags — the trigger vocabulary |
| Project board | Todo → In progress → In review → Done, driven by issue/PR state |
docs/ |
Source-of-truth docs the agent reads live and updates |
Onboard a new project¶
- Create the repo from the template. Inherits every workflow, label, board, and the docs scaffold.
- Write the source-of-truth docs. Design + status + decisions in
docs/— the agent's living context. - Register the team.
team_createnames the project's model mapping and points its context at those docs. - File issues, label
agent:go. The loop takes over: agent → PR → CI + preview → your review → merge.
Where things live¶
Three homes, chosen deliberately. Nothing sensitive is ever committed; workflow credentials live in GitHub; the AGX keeps only what local services need.
| What | Lives in | Why |
|---|---|---|
| CI / deploy secrets | GitHub Actions secrets / environments | Encrypted at rest, injected into jobs, scoped per environment |
| Local operational secrets | AGX env files (runner reads them) | Only local services and the on-box agent use these |
| Source of truth | The repo's docs/ |
Versioned, reviewable, read live and updated by the agent's PRs |
| Run state | GitHub issues + board + PRs | Replaces the bespoke queue / state.json — one legible record |
| Anything secret | Never the repo | .env is git-ignored; secrets reach jobs only via GitHub secrets |
Status¶
Honest accounting against this blueprint. The core loop is live and dogfooding itself — it has already shipped changes to this very repo, including fixing one of its own bugs by PR.
| Piece | State |
|---|---|
Self-hosted runner on the AGX (agx-orin) |
LIVE |
| Coding agent — Aider on local models via LiteLLM (no Claude) | LIVE |
| Mode 1 · issue → agent → PR → CI → merge → close | LIVE |
Mode 2 · new-project → scaffold repo from template |
LIVE |
| Self-repair — pipeline fixed its own bug via a merged PR | PROVEN |
| AURA host engine + supervisor on the AGX | LIVE |
| Telegram = notifier only (buttons removed) | DONE |
| Sandboxed host execution + live-doc context | CARRY OVER |
Orchestrated teams (planner / executor / reporter, team_create) — heavier path |
AVAILABLE |
| Per-repo runner + secrets auto-provisioned for scaffolded projects | NEXT |
| Nemo front door — file issues / new projects from chat | NEXT |
| Real per-project CI, preview + release workflows | NEXT |
request changes → re-trigger the agent on the same PR |
NEXT |