Architecture

This page maps nanobot's runtime behavior to source files. Use it when you are debugging internals, reviewing a PR, adding a provider/channel/tool, or trying to understand where a user-visible behavior comes from.

For the product-level mental model, read concepts.md first.

Core Flow

flowchart LR
    Channel["Channel
CLI, WebUI, chat apps"] --> Bus["MessageBus
InboundMessage"]
    Bus --> Loop["AgentLoop
session, workspace, context"]
    Loop --> Runner["AgentRunner
provider/tool loop"]
    Runner --> Provider["Provider
LLM backend"]
    Provider --> Runner
    Runner --> Tools["Tools
files, shell, web, MCP, cron"]
    Tools --> Runner
    Runner --> Loop
    Loop --> Outbound["MessageBus
OutboundMessage"]
    Outbound --> Channel

    Loop -. reads/writes .-> State["Session, memory,
hooks, skills, templates"]

Main files:

Agent Loop vs Agent Runner

AgentLoop owns the channel-facing turn:

• receives inbound messages;
• determines the effective session and workspace scope;
• builds context;
• wires hooks, progress, and channel metadata;
• publishes outbound messages.

AgentRunner owns the model-facing loop:

• sends messages to the selected provider;
• handles streaming deltas and reasoning blocks;
• executes tool calls;
• feeds tool results back into the model;
• stops when a final answer is produced or runtime limits are hit.

Keep this split in mind when debugging. If a problem is about channel routing, session keys, workspace selection, or outbound delivery, start in agent/loop.py. If it is about provider calls, tool calls, streaming, or iteration limits, start in agent/runner.py.

Providers

Provider metadata is centralized in nanobot/providers/registry.py. Configuration fields live in nanobot/config/schema.py.

Provider selection uses:

• explicit agents.defaults.provider or preset provider;
• provider registry keywords;
• API key prefixes and API base URL hints;
• local provider fallback when apiBase is configured;
• gateway fallback for providers that can route many model families.

Provider implementations live in nanobot/providers/. Most hosted providers use the OpenAI-compatible implementation, while Anthropic, Azure OpenAI, AWS Bedrock, OpenAI Codex, and GitHub Copilot have specialized paths.

Useful docs:

• providers.md for practical setup;
• configuration.md#providers for exact provider reference.

Channels

Channels translate external platforms into InboundMessage events and send OutboundMessage events back to the platform.

Main files:

Channels are discovered by scanning self-contained packages under nanobot/channels/. Add a channel by contributing one package that follows channel-package-guide.md.

WebUI and Gateway

nanobot gateway starts:

• enabled chat channels;
• the WebSocket channel when configured;
• workspace-scoped cron service;
• system jobs such as Dream and heartbeat;
• the health endpoint on gateway.port.

The packaged WebUI is served by the WebSocket channel, not the health endpoint:

WebUI source lives in webui/. The production build is written to nanobot/web/dist/ and bundled into the wheel.

Useful docs:

• webui.md for the WebUI user guide;
• ../webui/README.md for frontend source development;
• websocket.md for protocol details.

Tools

Tools are discovered from nanobot/agent/tools/ and plugin entry points.

Important files:

Tool behavior is part of the model contract. Keep user-visible tool names, schemas, and error messages stable unless a change is intentional.

Config and Paths

The config schema lives in nanobot/config/schema.py. Loading and saving live in nanobot/config/loader.py. Runtime path helpers live in nanobot/config/paths.py.

Defaults:

The schema accepts both camelCase and snake_case keys, but saves config with camelCase aliases.

Agent-Owned State vs Effective Project Context

Runtime code distinguishes the configured agent workspace from the effective project workspace carried by a session scope. They are often the same path, but a WebUI chat may select a separate project:

ContextBuilder combines project instructions with agent-owned profile and memory. Filesystem and search tools use the project as their ordinary boundary and receive only capability-specific read access to built-in/agent skills and the exact agent history file. Keep those cross-root capabilities read-only and explicit; do not treat the entire agent workspace as an allowed root.

Memory and Sessions

Session history is the near-term conversation replay. Memory is the longer-term workspace state.

Dream is implemented in nanobot/agent/memory.py and scheduled by the runtime when enabled.

Security Boundaries

Security-sensitive code paths include:

When changing tools, channels, file access, WebUI workspace behavior, or network fetching, treat security as part of the functional behavior and update docs if the user-facing boundary changes.

Extension Points

Prefer existing registry/discovery patterns over ad hoc wiring.

Testing and Verification

Common checks:

pytest tests/test_openai_api.py::test_function -v
ruff check nanobot/
cd webui && bun run test
cd webui && bun run build

Choose tests based on the changed surface:

For user-facing flows, prefer at least one verification path through the public surface the user actually touches: CLI command, HTTP endpoint, WebSocket/WebUI, chat channel, or packaged import.