nanobot

nanobot is built around one agent loop. A channel (WebUI, terminal, chat app) publishes an inbound message to a message bus; AgentLoop picks the session and workspace and builds context; AgentRunner calls the configured provider, executes tool calls and feeds results back until it has a final answer; the reply goes back out through the originating channel. nanobot gateway hosts the channels, the WebSocket server for the WebUI, cron jobs and background jobs such as memory consolidation.

Multi-agent work happens through a spawn tool: the main agent can start subagents for a task, either in the background or waiting for the result, with a concurrency cap. There is no separate role or graph layer. In the WebUI, one topic can also read another topic's context when the user mentions it.

State is split between ~/.nanobot/config.json (providers, channels, tools), the agent workspace (skills, memory files, cron jobs) and session history kept outside the workspace. Memory is layered: long conversations are summarised into memory/history.jsonl, and a Dream pass edits SOUL.md, USER.md and memory/MEMORY.md, with changes tracked in a Git repository inside the memory folder.

Control is conversational rather than approval-based. In the terminal UI, Ctrl+C stops a running turn, follow-up messages can be sent immediately or queued, and /diff shows the latest file edits; the WebUI shows reasoning, tool calls and diffs as they happen. Each topic has an access mode; in Restricted mode ordinary file and shell work stays inside the selected project. On chat channels, unknown users must be approved with /pairing approve <code> or listed in allowFrom. Scheduled automations can be paused, edited or deleted from the WebUI. No per-tool-call approval prompt is described in the README, concepts, WebUI, configuration or security docs.

python -m pip install nanobot-ai

python -m pip install nanobot-ai          # Python 3.11+
nanobot --version

# First run: creates ~/.nanobot/ and opens the WebUI at http://127.0.0.1:8765
# (pick a provider and model under Settings -> Models)
nanobot webui

nanobot -m "Summarise README.md in this folder"   # one-shot from the terminal
nanobot                                           # native terminal UI

# Optional: use a ChatGPT subscription through the OpenAI Codex provider
nanobot provider login openai-codex --set-main

# Keep channels and automations running after the terminal closes
nanobot gateway --background
nanobot gateway status

# OpenAI-compatible API on 127.0.0.1:8900
nanobot plugins enable api && nanobot serve

• Requires Python 3.11 or newer; Git and Bun are only needed for a source install.
• If pip reports externally-managed-environment, use the one-command installer, uv tool install nanobot-ai, pipx, or a virtual environment.
• Configure a model before first use (nanobot webui, then Settings -> Models); OAuth providers such as OpenAI Codex need nanobot provider login and an explicit provider in the preset.
• nanobot serve needs nanobot plugins enable api; binding the API to 0.0.0.0 requires api.apiKey.
• Since v0.1.4.post4 an empty allowFrom denies everyone on a channel; use pairing or set ["*"] deliberately.
• API keys sit in plain text in config.json unless you use ${VAR} references; Windows runs shell commands without a sandbox.
• The Render one-click deploy needs a paid Render service for persistent disks.

No. This record covers HKUDS/nanobot, published on PyPI as nanobot-ai and documented at nanobot.wiki. Other, unrelated projects use the same name.

Yes, as a client. It connects to MCP servers over stdio, HTTP or SSE, supports OAuth for remote servers, and can limit which tools each server exposes.

The docs do not describe driving those coding agents. OpenAI Codex and OpenCode Zen appear only as model providers (a ChatGPT-subscription login and an OpenCode-managed model gateway).

Yes. It is MIT licensed and has no paid tier; you pay only for the model provider you choose, or nothing with a local model.

The core and SDK are Python (3.11+); the terminal UI and WebUI are TypeScript and ship inside the PyPI wheels.