Skip to content

Architecture

This section describes how BOS is built and the principles that guide its design. It is the up-to-date source of truth — for the deeper, point-in-time rationale behind individual decisions, see the BEP Index.

Design principles

  • From zero to agent in one command. Sensible defaults; complexity is opt-in. A bare config runs; every layer (channels, sub-agents, custom tools) is something you add.
  • Minimal to start, project-ready. Start minimal and grow into a multi-agent project by editing one TOML file and dropping files into conventional directories — no rewrites.
  • Micro-kernel and plugins. A small core with well-defined extension points rather than a monolith. Tools, providers, channels, stores, consolidators, and plugins are all named, interchangeable implementations registered at an extension point.
  • Clean architecture. Dependencies point inward through concentric rings; the agent core stays free of framework and I/O concerns. Outer rings (harness, gateway, CLI) depend inward on the core, never the reverse.

How the pieces fit

                 ┌─────────────────────────── gateway process ───────────────────────────┐
 external client │   channel ──▶ mailbox ──▶ actor ──▶ agent (LLM loop) ──▶ tools/plugins  │
 (TUI/Telegram)  │     ▲                        │              │                           │
                 │     └──────── reply ─────────┘        harness services:                 │
                 │                                       chat_store, consolidator,         │
                 │                                       mail_route, job_runner            │
                 └────────────────────────────────────────────────────────────────────────┘
  • Gateway — the process that hosts actors and channels and serves a control plane. See Runtime & gateway.
  • Actors & agents — named, addressable runtime instances bound to LLM-driven agents. See Agents & actors.
  • Channels — how users reach an agent (TUI, Telegram, Lark, HTTP). See Writing channels.
  • Harness — the lifecycle owner of shared services (chat persistence, memory consolidation, message routing, background jobs), each selected by name in [harness].
  • Extension points — the micro-kernel seams. See Extending BOS.
  • Memory & skills — platform-managed memory with off-turn consolidation, and progressively-disclosed skill playbooks. See Memory & skills.

Where to read more

  • Concepts — the mental models in depth.
  • Configuration — how each part is configured.
  • Extending BOS — the extension-point model and how to build on it.
  • llm-full.md — a single dense, code-grounded reference of every mechanism, intended for ingestion by an AI agent. boscli init drops a copy into every project.

Deeper detail

The BEP Index links to the enhancement proposals that record the full design reasoning. BEPs capture point-in-time decisions and may contain detail that has since evolved — this section is the current reference.