Runtime and source map

This stage first makes nanobot complete a real request in an isolated learning workspace, then builds a map of the source. Do not start by reading agent/loop.py from the first line downward. First learn how the different entry points reach the core.

Corresponding source

Stage topic	Source
CLI, configuration, and first request	nanobot/cli/commands.py, nanobot/config/, nanobot/providers/
Entry-point convergence	nanobot/agent/loop.py::AgentLoop.process_direct, _process_message
Core execution	nanobot/agent/runner.py, nanobot/agent/context.py
Persistence and runtime surfaces	nanobot/session/manager.py, nanobot/channels/, nanobot/api/, nanobot/sdk/, nanobot/webui/

Learning objectives

After this stage, you should be able to:

• install nanobot from the current source snapshot;
• complete one non-interactive and one interactive request with DeepSeek;
• explain the main differences among CLI, Gateway, API, SDK, and WebUI;
• locate where each entry point eventually reaches AgentLoop;
• choose the right source starting point for a question.

Reading order

1. Complete your first request with DeepSeek
2. Five entry points and their runtime boundaries
3. Source tree and reading order
4. Minimal troubleshooting flow

Out of scope for this stage

• Do not connect a chat platform.
• Do not configure MCP.
• Do not modify the nanobot source.
• Do not start a production deployment.
• Do not study the React WebUI in depth.
• Do not try to understand every Provider at once.

Why start with the CLI?

The nanobot agent -m path is short and has few peripheral variables. It is the best first proof that installation, configuration, Provider, model, and workspace all work. Study Gateway, Channel, and WebUI only after the core call succeeds.

Minimal runtime map

flowchart LR
    CMD["nanobot agent -m"] --> CLI["cli/commands.py::agent"]
    CLI --> CFG["Load Config"]
    CFG --> LOOP["AgentLoop.from_config"]
    LOOP --> DIRECT["AgentLoop.process_direct"]
    DIRECT --> TURN["_process_message / TurnState"]
    TURN --> RUNNER["AgentRunner.run"]
    RUNNER --> DS["DeepSeek API"]
    DS --> RUNNER
    RUNNER --> SAVE["Save Session"]
    SAVE --> CLI

Choosing an entry point

Goal	Preferred entry point
Verify configuration and model	nanobot status, nanobot agent -m
Multi-turn terminal conversation	nanobot agent
Long-running Channels, WebUI, and Cron	nanobot gateway
OpenAI-compatible HTTP interface	nanobot serve
Embed in a Python program	Nanobot SDK
Browser interaction	WebSocket Channel + Gateway + WebUI

Next step

Begin with Complete your first request with DeepSeek.