aido-orchestrator · the gateway

One MCP plug,
three bodies,
one agent loop.

aido-orchestrator is the conversation gateway. It speaks MCP upstream to your LLM client, MCP downstream to aido-runtime + aido-vm + aido-browser, and exposes a unified surface of 101 tools with name-prefix routing.

Plus: the agent loop itself (conversation state, LLM provider, subagent spawn), ~50 slash commands, Claude OAuth flow, HTTP/SSE serve mode, project detection, session logger. The thing that turns 4 crates into one agent experience.

read the role → github

MCP downstreams

101

unified tools

~50

slash commands

frontends · CLI · TUI · HTTP

gateway · routing live gateway

› /goalhandled local

↓

→ read_fileaido-runtime

↓

→ simulateaido-runtime

↓

→ browser_navigateaido-browser

↓

→ vm_screenshotaido-vm

↓

→ safe_changeaido-runtime

routing by name prefix · vm_* · browser_* · slash · runtime ●

role

Six jobs in one binary.

aido-orchestrator does six things at once. None of them belong in aido-runtime (which stays a pure typed executor), and none belong in aido-code (which is just a TUI). The orchestrator is the glue.

job 01

MCP gateway · multi-downstream

Spawns and supervises aido-runtime, aido-vm-mcp and aido-browser-mcp as MCP children. Routes incoming tools/call by name prefix.

vm_* → aido-vm 29 tools
browser_* → aido-browser 14 tools
everything else → aido-runtime 58 tools

job 02

Agent loop · conversation

The main loop: parse user turn → build system prompt → call LLM → execute tool calls → splice results → next turn. Backpressure, interrupts, cost tracking, token budget.

conversation.rsstate
agent_loop.rsmain loop
parser.rstool-call extract
interrupt.rsctrl-c

job 03

Slash commands · ~50

Typed dispatcher. Not LLM calls · deterministic local actions. /goal persists intent, /auto toggles autonomous, /diff reads git, /restore rolls back via runtime.

slash.rsdispatcher
goal/persistent intent
pulse.rshealth signals

job 04

LLM provider abstraction

One trait, five providers. Claude OAuth (anthropic.com), Anthropic API, OpenAI, Mistral, Ollama. /model hot-swaps mid-session. Per-turn cost in the sticky header.

llm_setup.rsinit
claude_oauth.rsclaude.ai flow
api.rsusage tracker

job 05

Sandbox bootstrap

Incus or Podman wrap. Detects available engines, creates the container if missing, bind-mounts the project, forwards artifact ports. The host filesystem stays unreachable.

container_runtime.rsincus · podman
artifact_expose.rsport-forward
bridge.rsruntime conn

job 06

Three frontends · one core

The same agent loop drives a CLI (rustyline), a TUI (ratatui with sticky header + conversation panel + sysmon), and an HTTP/SSE serve mode for web embedding.

tui.rs · app.rsratatui
terminal.rsCLI
serve.rs/prompt + /events

three downstreams

One gateway, three bodies.

The orchestrator boots its MCP children lazily · only what the agent actually uses pays the spawn cost. AIDO_VM_DOWNSTREAM=1 turns on the VM body; AIDO_BROWSER_DOWNSTREAM=1 turns on browser. Both are off by default to keep startup snappy.

58 tools · always on

aido-runtime

The typed primitive surface: simulate, snapshot, safe_change, pipeline, custom functions, memory, events, desktop, artifacts, network, LLM bridge. Boots in-process via aido_runtime::execute_action or out-of-process via stdio.

routes * (no prefix)

29 tools · opt-in

aido-vm

QEMU/KVM body for computer-use without putting the host at risk. Screenshots, OCR, snapshots in ~2 s, linked-clone pool. Lazy-spawned when the agent emits its first vm_* call.

routes vm_*

14 tools · opt-in

aido-browser

Isolated Chromium via CDP. Allowlist + audit + rate limit + abort switch. For frontend dev loops · the agent tests your localhost without touching your real browser.

routes browser_*

# Wire all three downstreams AIDO_VM_DOWNSTREAM=1 AIDO_BROWSER_DOWNSTREAM=1 \ aido-orchestrator --mcp # From a Claude Code / Codex perspective · single .mcp.json entry { "mcpServers": { "aido": { "command": "aido-orchestrator", "args": ["--mcp"], "env": { "AIDO_VM_DOWNSTREAM": "1", "AIDO_BROWSER_DOWNSTREAM": "1" } } } } # → 101 unified tools, one MCP connection, name-prefix routing.

slash commands

The local dispatcher · ~50 commands.

Slash commands are the orchestrator's deterministic path · no LLM round-trip, no tool call, just typed Rust. /goal writes to persistent memory. /restore calls runtime. /auto flips a state machine. They're the keyboard shortcuts of the agentic shell.

/goal

Persistent goal across turns.

/auto

Toggle autonomous mode.

/policy

Inspect / edit policy.

/restore

Roll back to last snapshot.

/snapshot

Create named snapshot.

/commit

git commit + generated msg.

/diff

Working-tree diff.

/model

Hot-swap LLM.

/provider

Switch provider.

/auth

Auth status + flows.

/login

Claude OAuth.

/budget

Max $ per session.

/cost

Per-turn breakdown.

/bench

Benchmark suite.

/check

Poll an async handle.

/stop

Stop an async handle.

/handles

List async handles.

/mem

Memory store.

/remember

Pin a fact.

/session

Session log + replay.

/history

Conversation history.

/expand

Full history dump.

/compact

Summarize + compress.

/clear

Clear, keep memory.

/output

Verbose toggle.

/log

Tail runtime logs.

/error

Re-show last error.

/read

Quick file inspect.

/sh

One-shot sandboxed shell.

/artifact

Inspect / serve artifact.

/artifacts

List all artifacts.

/pulse

Live health signals.

/save-config

Persist current config.

/setup

Re-run wizard.

/help

List all commands.

/quit

Exit cleanly.

three frontends

Same agent loop, three skins.

The orchestrator's agent loop is frontend-agnostic. Three display sinks ship out of the box; the loop emits structured events, each sink renders them differently.

01 · CLI

Interactive shell

rustyline + colored output. Default mode. Slash commands, history, multi-line input with \. Best for headless and SSH sessions.

02 · TUI

ratatui frontend

Full-screen TUI with sticky header (project / tokens / cost / sandbox status), conversation pane, system monitor side-panel. Launch with aido --tui.

03 · HTTP

Serve mode

aido --serve --port 8080 exposes /prompt (POST) + /events (SSE) for web frontends. Bearer-token-gated. Same agent loop streaming JSON.

architecture

The gateway, drawn.

aido-orchestrator is the only crate that talks to all of them. aido-code uses it as a library to build the TUI; external MCP clients (Claude Code, Codex, Cursor) use the aido-orchestrator --mcp binary as a single MCP server with 101 unified tools.

CLI · TUI · HTTP/SSE · MCP upstream │ │ │ │ └─────┴───────┴──────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────┐ │ aido-orchestrator │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ agent_loop │ │ slash │ │ llm_setup │ │ │ │ conversation│ │ dispatcher │ │ + claude_oauth │ │ │ └──────┬──────┘ └──────┬──────┘ └─────────────────┘ │ │ │ │ │ │ └────────┬───────┘ │ │ │ tool_call / slash_call │ │ ▼ │ │ ┌────────────────────────────────────────────────┐ │ │ │ mcp_server · routing by name prefix │ │ │ └──────────┬──────────┬──────────┬───────────────┘ │ └─────────────┼──────────┼──────────┼─────────────────────┘ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │ aido- │ │ aido-vm- │ │ aido-browser-│ │ runtime │ │ mcp │ │ mcp │ │ 58 prim │ │ 29 vm_* │ │ 14 browser_* │ └──────────┘ └──────────┘ └──────────────┘

# Routing logic · name-prefix dispatch (mcp_server.rs) match tool_name { n if n.starts_with("vm_") => vm_downstream.call(n, args).await, n if n.starts_with("browser_") => browser_downstream.call(n, args).await, n => runtime_downstream.call(n, args).await, }

One MCP plug, three bodies, one agent loop.