# nanobot: features, protocols, quickstart

## TL;DR

nanobot is an MIT-licensed, self-hosted personal AI agent written in Python and maintained under the HKUDS GitHub organisation. One gateway serves a WebUI, terminal UI and chat apps such as Telegram, Slack and WeChat, with MCP tools, layered memory, subagents and scheduled automations. It suits individuals running their own always-on assistant.

## Key facts

| Field | Value |
| --- | --- |
| Type | Harness |
| Languages / SDKs | Python, TypeScript |
| License | MIT |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 48,697 (as of 2026-09-30) |
| GitHub forks | 8,597 |
| Last push | 2026-09-30 |
| Latest release | v0.3.5 |
| Repository | [HKUDS/nanobot](https://github.com/HKUDS/nanobot) |
| Website | [nanobot.wiki](https://nanobot.wiki) |
| Documentation | [nanobot.wiki](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview/) |
| Last verified | 2026-09-30 |

## Key features

- `nanobot gateway` runs one agent loop behind several entry points: the WebUI, a terminal UI, a one-shot CLI and chat channels such as Telegram, Discord, Slack, Feishu, WeChat, Email, Mattermost and Linear. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/concepts.md))
- MCP servers (stdio, HTTP or SSE, with optional OAuth) are added through the Apps page or `tools.mcpServers`, and `enabledTools` limits which of their tools the model sees. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-mcp-tools.md))
- The agent can spawn background subagents for separate tasks; by default four run at once (`agents.defaults.maxConcurrentSubagents`) and extra ones wait. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/configuration.md))
- Layered memory: live session messages, a compressed `memory/history.jsonl` archive, durable `SOUL.md`, `USER.md` and `MEMORY.md` files, a Dream consolidation pass and Git history for memory edits. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/memory.md))
- The WebUI shows reasoning, tool calls, file diffs and per-round context usage, and can place up to four topics side by side. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/webui.md))
- Providers include hosted APIs, local OpenAI-compatible servers such as Ollama and vLLM, and OAuth subscriptions such as OpenAI Codex and GitHub Copilot. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/providers.md))
- A Python SDK (`Nanobot.from_config()`) and an OpenAI-compatible `/v1/chat/completions` endpoint (`nanobot serve`) expose the same runtime to other programs. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/python-sdk.md))
- Shell commands can run inside an OS sandbox (bubblewrap on Linux, Seatbelt on macOS), which also restricts file tools to the workspace. ([source](https://github.com/HKUDS/nanobot/blob/main/SECURITY.md))

## Architecture and orchestration pattern

Pattern: Supervisor.

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.

### Human in the loop

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.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-mcp-tools.md) | Client: nanobot connects to MCP servers over stdio, HTTP or SSE (with OAuth for remote servers) and exposes their tools to the model, with per-server tool allowlists. |
| A2A | Unknown (checked 2026-09-30) | — | No mention of A2A in the README or docs (concepts, architecture, configuration, WebUI, providers, agent social network); GitHub code search for 'a2a' only matched a commit hash in a test file and a lock file. |
| AG-UI | Unknown (checked 2026-09-30) | — | No mention of AG-UI in the README or docs; GitHub code search for 'ag-ui' returned nothing, and nanobot is not listed in the AG-UI README. |

## Best for

- Running a personal assistant on your own machine or server that you can reach from Telegram, Slack, Discord, WeChat or email. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Using local models through Ollama, vLLM or another OpenAI-compatible server. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Scheduled or long-running agent jobs that report back into a chat topic.
- Python developers who want an agent runtime with tools and memory behind an SDK or an OpenAI-compatible endpoint.

## Not for

- Building structured multi-agent systems with roles or graphs; multi-agent support is limited to spawning subagents.
- Windows deployments that need sandboxed shell commands; there is no sandbox backend on Windows.
- Public multi-user services that need rate limiting and audit logs, which the security policy lists as missing.

## Quickstart

```sh
python -m pip install nanobot-ai
```

Install not yet verified by this site.

```bash
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
```

### Common pitfalls

- 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.

Official quickstart: https://github.com/HKUDS/nanobot/blob/main/README.md

## Pros

- One gateway covers browser, terminal and many chat apps, so the same agent and memory are reachable from each. ([source](https://github.com/HKUDS/nanobot/blob/main/README.md))
- Wide provider choice, including local models and subscription logins, with fallback presets. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/providers.md))
- Memory changes are versioned in Git and consolidated by a documented Dream process rather than an opaque store. ([source](https://github.com/HKUDS/nanobot/blob/main/docs/memory.md))
- Optional kernel-level sandbox for shell commands on Linux and macOS. ([source](https://github.com/HKUDS/nanobot/blob/main/SECURITY.md))
- MIT licensed with no paid tier, and frequent releases (v0.2.0 in May to v0.3.5 in September 2026). ([source](https://github.com/HKUDS/nanobot/releases))

## Cons

- The security policy lists known gaps: no rate limiting, API keys in plain-text config, no session expiry, limited command filtering and no audit trail. ([source](https://github.com/HKUDS/nanobot/blob/main/SECURITY.md))
- Multi-agent support is a subagent spawn tool; an open proposal asks to evolve it toward real multi-agent collaboration. ([source](https://github.com/HKUDS/nanobot/issues/5000))
- An open issue with 14 comments reports high token consumption. ([source](https://github.com/HKUDS/nanobot/issues/5266))
- Pre-1.0 software with frequent releases; the README points users who want stability to PyPI releases rather than source. ([source](https://github.com/HKUDS/nanobot/blob/main/README.md))

## Alternatives

- [OpenClaw](https://multiagentguide.top/tools/openclaw.md)
- [Hermes Agent](https://multiagentguide.top/tools/hermes-agent.md)
- [Letta](https://multiagentguide.top/tools/letta.md)
- [AnythingLLM](https://multiagentguide.top/tools/anything-llm.md)

## FAQ

### Is this the same as other projects called nanobot?

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

### Does nanobot support MCP?

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.

### Can nanobot run Claude Code or Codex?

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).

### Is nanobot free?

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.

### What language is nanobot written in?

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

## Sources

- [nanobot GitHub repository (HKUDS)](https://github.com/HKUDS/nanobot)
- [nanobot README](https://github.com/HKUDS/nanobot/blob/main/README.md)
- [nanobot.wiki](https://nanobot.wiki)
- [nanobot overview (nanobot.wiki)](https://nanobot.wiki/docs/latest/getting-started/nanobot-overview/)
- [Concepts](https://github.com/HKUDS/nanobot/blob/main/docs/concepts.md)
- [How to configure MCP tools](https://github.com/HKUDS/nanobot/blob/main/docs/guides/configure-mcp-tools.md)
- [Configuration reference](https://github.com/HKUDS/nanobot/blob/main/docs/configuration.md)
- [Memory](https://github.com/HKUDS/nanobot/blob/main/docs/memory.md)
- [WebUI guide](https://github.com/HKUDS/nanobot/blob/main/docs/webui.md)
- [Providers and models](https://github.com/HKUDS/nanobot/blob/main/docs/providers.md)
- [Python SDK](https://github.com/HKUDS/nanobot/blob/main/docs/python-sdk.md)
- [OpenAI-compatible API](https://github.com/HKUDS/nanobot/blob/main/docs/openai-api.md)
- [Security policy](https://github.com/HKUDS/nanobot/blob/main/SECURITY.md)
- [Spawn tool source (subagents)](https://github.com/HKUDS/nanobot/blob/main/nanobot/agent/tools/spawn.py)
- [nanobot releases](https://github.com/HKUDS/nanobot/releases)
- [Issue #5000: evolve the subagent system toward multi-agent collaboration](https://github.com/HKUDS/nanobot/issues/5000)
- [Issue #5266: token consumption](https://github.com/HKUDS/nanobot/issues/5266)

## Unknown fields

protocols.a2a and protocols.agui: no mentions in the README or the docs listed in sources; GitHub code search found 'a2a' only inside a commit hash in tests/agent/test_dream.py and in webui/bun.lock, and nothing for 'ag-ui'; nanobot is not in the AG-UI README. harnesses is empty because the docs describe no integration that runs or plugs into Claude Code, Codex, OpenCode, OpenClaw or Hermes: OpenAI Codex and OpenCode Zen/Go are model providers, and OpenClaw is mentioned only as a comparison for the gateway workflow. All sources are the HKUDS/nanobot repository or nanobot.wiki.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/nanobot