Skip to content

Architecture overview

Earlier technical reference

This page is retained from earlier documentation and has not been fully revalidated for the public 2026.10.19 release. Its revision-specific links and examples may describe older or development behavior. Start with the current public-release user guide; do not use this page alone to select installation commands, image tags, or security settings.

BURROW separates the operator surface, runtime orchestration, authoritative state, execution placement, and provider transport. This keeps the conversational interface small while preserving inspectable evidence for work performed behind it.

Component map

flowchart TB
    UI[Browser UI or API client] --> HTTP[HTTP server and authentication]
    HTTP --> CT[ChatTurnController]
    CT --> RT[Application runtime]
    RT --> CX[Context preparation and assembly]
    RT --> PG[(PostgreSQL application stores)]
    CX --> OR[RuntimeOrchestrator]
    OR --> MA[Model adapters]
    MA --> MP[Configured model provider]
    OR --> EX[Reviewed tool executor]
    EX --> LOCAL[Local process and filesystem tools]
    EX --> REMOTE[Registered remote execution controller]
    EX --> MCP[Granted MCP and mod tools]
    EX --> CHILD[Minion execution]
    EX --> PG
    OR --> FIN[Terminal finalization]
    FIN --> PG
    RT -.-> TRACE[Trace cache and artifacts]
    EX -.-> TRACE
    FIN --> HTTP

The HTTP entrypoint is backend/scripts/burrow-ui.mjs; transport normalization is in chat-turn-controller.mjs; app-runtime.mjs composes the turn. The model/tool loop belongs to runtime-orchestrator.mjs.

Ownership boundaries

Component Owns Must not be mistaken for
UI / HTTP transport Input, authentication, response/stream presentation Model or tool authority
Application runtime Turn preparation, trusted agent context, continuity ownership, terminal coordination A prose classifier that automatically grants actions
Context builder Selection and provider-ready context assembly A second durable conversation store
Runtime orchestrator Model calls and native tool continuations UI rendering or deployment management
Model adapter Provider serialization, stream decoding, normalized response Conversation persistence
Tool executor Concrete dispatch and execution-time validation A promise that every requested action ran
PostgreSQL stores Configuration and current conversation/state authorities Trace files or release contents
Runtime filesystem Workspaces, artifacts, trace/cache files, release material Universal settings or conversation authority

Normal chat fixes the route as a model-owned chat turn. Planning and route metadata are diagnostic/support information, not an independent execution engine.

State root versus execution root

The controller must retain its agent/session state even when tools execute elsewhere. A remote assignment therefore changes the execution target, not the owner of PostgreSQL conversations or profile configuration. Each tool result can carry execution origin and correlation identifiers.

The built-in UI uses only its serving runtime, with relative API paths. There is no remote API-target selector. Backend execution placement remains separate:

Selection Changes Does not establish
Agent execution environment Local execution, or a remote providerId/targetId for supported tools A new agent identity or a migration of controller-owned state
Filesystem target / command cwd The directory used as task context or a command's working directory Host choice, permission grants, or OS containment

An execution host, sometimes called a node by an integration, is an execution placement. It is not a registered agent or minion. The core router requires a live registered controller for a remote target; an unavailable controller fails the operation rather than falling back to the controller host. Provider-specific host discovery, enrollment, and transport belong to that integration's contract.

See Interface runtime ownership and Agent execution environments before operating across multiple runtimes or hosts.

Agent workspace and target paths establish context and defaults. They do not create a filesystem sandbox.

See Persistence, Trust boundaries, and Tools.

Conversation versus observability

The current conversation is authoritative for what was said. Provider messages are a prepared projection, not a byte-for-byte copy of every stored event.

The runtime keeps separate channels for:

  • Chat-visible user, assistant, and attributed agent messages
  • Activity events for useful progress
  • Tool calls/results and compact execution digests
  • Receipts and debug information
  • Raw diagnostic artifacts

Raw receipts, tool protocol, and debug entries do not all become future conversation. The finalizer deliberately adds a bounded execution digest when appropriate.

Extension boundaries

Skills extend instructions; MCP and mod capabilities extend tool availability; model adapters extend provider contracts. These are separate responsibilities. A skill cannot grant an unconfigured tool, and a discovered tool is not necessarily granted.

See Extensions, MCP, and Models.

Read the architecture in depth