nanobot Documentation

File: README.md Copy Chapter

nanobot

🐈 nanobot is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.

Start Here Copy Chapter

What can nanobot do? Copy Chapter

nanobot is a self-hosted personal AI agent runtime. It can:

• run in a browser WebUI or terminal
• connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, and other chat apps
• use tools such as files, shell, web search, web fetch, MCP, cron, image generation, and subagents
• keep session history and long-term memory through Dream
• run long-horizon goals and scheduled automations
• expose a Python SDK and OpenAI-compatible API for integrations
• deploy as a long-running local or server-side agent gateway

💡 Why nanobot Copy Chapter

• Persistent workflows: goals, memory, tools, and chat context survive long-running work.
• Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, and Mattermost.
• Model freedom: OpenAI-compatible APIs, local LLMs, image generation, search, and fallbacks.
• Small core: readable internals with MCP, memory, deployment, and automation built in.
• Own your stack: inspect, customize, self-host, and extend without a giant platform.

📦 Install Copy Chapter

[!IMPORTANT]
If you want the newest features and experiments, install from source.

If you want the most stable day-to-day experience, install from PyPI or with uv.

Pick one install method:

Prerequisites: Python 3.11 or newer. Git and Bun are only needed for a source install. Published packages include the WebUI and fetch a checksummed, version-matched TUI archive—with its licenses, notices, corresponding application source, source offer, and relinking instructions—on first use.

If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in Start Without Technical Background instead of this compact README path.

One-command setup

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

The default command installs or upgrades nanobot-ai from PyPI. On a fresh local desktop, it then starts nanobot webui so you can configure the first provider and model in Settings → Models. SSH, headless, existing-config, and older-release paths keep the terminal setup wizard. The installer avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. It also prints the exact command it used to run nanobot; reuse that full command below if nanobot is not on PATH.

To preview the plan without changing your environment, pass --dry-run.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

If you prefer to inspect the script first, open scripts/install.sh or scripts/install.ps1.

Install with uv

uv tool install nanobot-ai

Install from PyPI with pip

python -m pip install nanobot-ai

If pip reports externally-managed-environment on macOS or Linux, use the one-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or install inside a virtual environment.

Install from source

Clone the repository and install it in editable mode. Bun is required because the source
checkout runs the matching TUI directly instead of downloading an older release binary.

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m venv .venv

Activate it with source .venv/bin/activate on macOS/Linux or
.venv\Scripts\Activate.ps1 in Windows PowerShell, then run:

python -m pip install -e .

After that, the normal commands are identical to a stable install. nanobot agent runs the TUI
from this checkout, and nanobot webui rebuilds stale frontend assets automatically. A later
git pull --ff-only updates the Python, TUI, and WebUI source together; rerun
python -m pip install -e . when Python dependencies change. Contributors should also read
CONTRIBUTING.md.

Verify the install:

nanobot --version

If nanobot is not on PATH, invoke it through the method that installed it: reuse the recommended installer's command, use uv tool run --from nanobot-ai nanobot ... or pipx run --spec nanobot-ai nanobot ..., or use the Python executable from the environment where pip installed the package.

🚀 Quick Start Copy Chapter

Open nanobot in your browser

nanobot webui

This is the recommended first run. The launcher creates the config and workspace when needed, safely enables the local WebSocket channel after confirmation, starts or joins the shared local gateway, and opens http://127.0.0.1:8765. A fresh install can open before a model is configured, so setup continues in the browser instead of beginning in a JSON file. The first-run WebUI binds to localhost by default and is not exposed to your LAN.

Your first three steps

1. Open Settings → Models and choose a provider, credential, and model.
2. Start a new topic and send Hello! to verify the connection.
3. Before project work, choose the intended workspace and access mode from the composer.

Any normal reply means the provider, model, workspace, and browser gateway are working together.

Keep nanobot running after you close the terminal

nanobot gateway --background

This is the only command that promotes the shared gateway to persistent background mode. It leaves channels and automations running after every local TUI and WebUI launcher exits. Complete first-time model setup with nanobot webui before switching to background mode; open the same localhost WebUI again afterward.

nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop

Prefer a gateway-first workflow?

nanobot gateway

This skips WebUI setup and browser opening, then runs the same complete gateway in the current terminal. It is the familiar entry point if you are coming from OpenClaw or already operate agents as long-lived services. The WebUI remains available when its channel is configured; open it manually when needed.

Use nanobot gateway --background for the same direct entry point without keeping the terminal attached. For automatic startup and supervision by the operating system, see Deployment.

Prefer to work entirely in the terminal?

nanobot agent

This opens the native terminal client with the configured model and tools, using the launch directory as its workspace. Use /sessions to switch saved conversations, /new-chat to preserve this conversation and start another one, /branch to fork from a completed reply, /context to inspect the compacted summary and raw message suffix available to the agent, or /diff to review the latest turn's file changes. Type @ to mention an installed app, configured MCP server, or saved session. While nanobot is working, Enter steers the current turn, Tab queues a visible follow-up for the next turn, and Option+Up on macOS (Alt+Up on Windows/Linux) returns the latest queued message for editing. Press Shift+Enter to add a newline; Ctrl+J is the universal fallback for terminals that cannot distinguish modified Enter keys. Use PageUp at the top to load earlier transcript pages. Each launch starts a new session; --session selects an existing WebSocket session, while --workspace overrides the launch directory. Use --classic to resume a session from another channel. The existing nanobot /new command keeps its original behavior: it resets the current chat. nanobot agent and nanobot webui share one on-demand local gateway: either command can start it, each launcher releases only its own client, and the last interactive launcher to exit stops it. Use nanobot gateway --background when the gateway must stay alive with no local clients. Type exit or press Ctrl+C when you are done; after the terminal is restored, nanobot prints a ready-to-run nanobot agent --session ... command that resumes the session. Use nanobot agent --classic for the legacy Python prompt.

For one request and an immediate exit, use:

nanobot agent -m "Hello!"

The one-shot form is useful for a quick provider check, shell scripts, and local automation. If you have not configured a model yet, run nanobot webui and open Settings → Models first.

Need manual JSON, another device on your LAN, or help with provider/model matching? Continue with Install and Quick Start, WebUI, or Troubleshooting.

If nanobot worked for you, a star on GitHub is the simplest way to support the project.

• Want a pasteable provider setup? See Provider Cookbook
• Want to understand provider/model matching? See Providers and Models
• Want web search, MCP, security settings, or more config options? See Configuration
• Want to run locally? See Ollama, vLLM or another local OpenAI-compatible server, and the full provider reference.
• Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See Chat Apps
• Want Docker or Linux service deployment? See Deployment

☁️ Deploy Copy Chapter

Render — one click

Deploy nanobot's gateway and bundled WebUI from the repository's ready-to-use Blueprint:

Render will ask for ANTHROPIC_API_KEY and a private NANOBOT_WEB_TOKEN, then provision persistent storage for sessions, memory, and WebUI history. Persistent disks require a paid Render service.

Self-host

Prefer your own infrastructure? Follow the deployment guide for Docker, Docker Compose, Linux services, and macOS LaunchAgent setup.

🌐 WebUI Copy Chapter

The WebUI ships inside the published wheel with no separate frontend build. It is the browser workbench for persistent topics, temporary chats, visible agent activity, workspace controls, Apps, Skills, Automations, and settings.

Use it to:

• keep separate topics for different tasks and projects;
• use temporary chats when a conversation should not be saved to history or memory;
• inspect reasoning, tool calls, file edits, diffs, command output, and generated artifacts;
• switch models and workspaces without leaving the conversation;
• configure providers and chat channels, connect Apps, discover Skills, and manage Automations from one place.

See the WebUI guide for LAN access, background operation, workspace controls, and the full feature tour. Working on the frontend itself? Use webui/README.md.

🏗️ Architecture Copy Chapter

🐈 nanobot stays lightweight by centering everything around a small agent loop: messages come in from chat apps, the LLM decides when tools are needed, and memory or skills are pulled in only as context instead of becoming a heavy orchestration layer. That keeps the core path readable and easy to extend, while still letting you add channels, tools, memory, and deployment options without turning the system into a monolith.

📚 Docs Copy Chapter

Browse the repo docs for the latest features and GitHub development version, or visit nanobot.wiki for the stable release documentation.

• Use task-oriented guides: Guides
• Start with no technical background: Start Without Technical Background
• Start from zero with developer basics: Install and Quick Start
• Understand the runtime model: Concepts
• Read the source-level map: Architecture
• Choose a provider/model: Providers and Models
• Copy provider setup recipes: Provider Cookbook
• Debug setup and runtime failures: Troubleshooting
• Talk to your nanobot with familiar chat apps: Chat App AI Agent · Chat Apps
• Schedule or trigger agent work: Automations
• Configure providers, web search, MCP, and runtime behavior: Configuration
• Integrate nanobot with local tools and automations: OpenAI-Compatible API · Python SDK
• Run nanobot with Docker or as a Linux service: Deployment

Releases Copy Chapter

Latest release: v0.3.0 - The Agency Release

The Agency Release turns nanobot from a durable workbench into an agent runtime that can coordinate helpers, switch models per session, and carry authorized work through to completion.

• Consult inline subagents without leaving the current task
• Switch model presets per session directly from the composer
• Start from a guided WebUI setup with clearer execution controls
• Apply configuration changes live across a more reliable provider, channel, and tool runtime

Read the v0.3.0 release notes

Recent Updates Copy Chapter

• 2026-07-24 Guided first-run setup, inline subagents, and model switching from the composer.
• 2026-07-23 Grok OAuth with hosted X Search, live image settings, and clearer fallback models.
• 2026-07-22 Parallel Search, live configuration reloads, richer app discovery, and a smoother mobile WebUI.
• 2026-07-21 Codex fast mode, visible skill references, safer configuration saves, and sturdier task cleanup.
• 2026-07-20 Cleaner code blocks and copy actions, self-contained channels, and steadier QQ reconnects.

For older updates, see the release archive or GitHub releases.

Open Source Partners Copy Chapter

🤝 Contribute Copy Chapter

Use nanobot for a real task, report what broke, and then pick a focused improvement.

• Read CONTRIBUTING.md for the development workflow.
• Browse open issues for problems to investigate.
• Open a pull request for a focused fix or integration.

Contact Copy Chapter

Nanobot was started by Xubin Ren as a personal open-source project and is now maintained collaboratively with contributors from the open-source community. Feel free to contact [email protected] for questions, ideas, or collaboration.

Contributors Copy Section

File: nanobot/skills/README.md Copy Chapter

nanobot Skills

This directory contains built-in skills that extend nanobot's capabilities.

Skill Format Copy Chapter

Each skill is a directory containing a SKILL.md file with:

• YAML frontmatter (name, description, metadata)
• Markdown instructions for the agent

When skills reference large local documentation or logs, prefer nanobot's built-in
grep tool to narrow the search space before loading full files.
Use grep(output_mode="count") / files_with_matches for broad searches first,
use head_limit / offset to page through large result sets,
and grep(glob="*.md") to filter by file name pattern.

Attribution Copy Chapter

These skills are adapted from OpenClaw's skill system.
The skill format and metadata structure follow OpenClaw's conventions to maintain compatibility.

Available Skills Copy Chapter

File: docs/README.md Copy Chapter

nanobot Documentation

Use these docs to get a working agent first, then open a task guide only when you need the next capability. Source-level design and extension details are kept in the contributor section.

Repository docs follow the current source tree and can be newer than the latest package release. For published release docs, visit nanobot.wiki.

Start Here Copy Chapter

The recommended first-run path is:

1. Install nanobot.
2. Let the installer open nanobot webui on a fresh local desktop.
3. Configure a provider and model in Settings → Models.
4. Send Hello! before configuring anything else.

Most people do not need to edit JSON for the first run. The WebUI handles the initial provider, model, and local browser settings. SSH, headless, existing-config, and older-release installs retain nanobot onboard --wizard as a terminal fallback. After the WebUI opens, use Settings for models and built-in capabilities, Settings → Channels for chat apps, and Apps for Agent Plugins, CLI Apps, and MCP integrations.

Add One Capability Copy Chapter

Pick the row that matches what you want to accomplish next:

For shorter, outcome-focused walkthroughs, browse the task guide index.

Operate nanobot Copy Chapter

Reference Copy Chapter

Use reference pages to look up an exact option after you know what you are trying to configure:

Configuration examples are usually snippets to merge into ~/.nanobot/config.json, not complete replacement files. The docs use camelCase because nanobot writes config that way. Keep real API keys, bot tokens, and passwords out of issues and public logs.

Extend or Contribute Copy Chapter

These pages explain implementation and extension points. You do not need them to install or operate nanobot.

If a command or screen no longer matches these docs, please open an issue with your nanobot version, operating system, and the page that needs correction.