🐈 nanobot is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. Use it in a browser, terminal, or chat app to work with files, remember preferences, and schedule tasks. Connect a supported model provider or local model server to supply the AI.

nanobot can:

• run in a browser WebUI or terminal
• connect to Telegram, Discord, Slack, WeChat, Email, Mattermost, Linear, and other channels
• read PDF, Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) files with built-in file tools, for tasks such as summarizing reports
• use shell, web search/fetch, MCP integrations, cron, image generation, and multi-agent delegation
• 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

• Persistent workflows: keep saved conversations, long-term memory, and task results for later work.
• Chat-native reach: WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, and Linear.
• 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.

You need Python 3.11 or newer and access to a supported model provider or local model server. Model fees or local hardware requirements depend on the service you choose; nanobot does not supply a model account.

Choose the stable release for everyday use or current source for development and the latest features. This README describes current source; published documentation covers the released version.

New to terminals or model credentials? Follow Start Without Technical Background. Updating an existing instance? Back up its config directory and workspace, stop every old nanobot process using that workspace, then update and restart through the original launcher or service. See session storage and version changes.

Stable release: automatic setup (recommended)

The installer chooses an isolated Python environment and opens setup for you. The two commands below are the same installation method for different operating systems; run only the one for your system.

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

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

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

uv tool install nanobot-ai

python -m pip install nanobot-ai

Current source: development checkout

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

python -m pip install -e .

nanobot --version

After installation, continue with Quick Start. Use the exact command printed by the installer if nanobot is not on PATH.

Open nanobot in your browser

If the installer already opened the WebUI, continue there. Otherwise run:

nanobot webui

Keep the launcher terminal open while using the browser. It starts or joins the shared local gateway and binds the first-run WebUI to localhost. If the browser does not open, copy the complete login link printed in the terminal, including everything after #; keep this credential private. For SSH or a headless host, use the remote-browser or terminal-only instructions below.

Your first three steps

1. Open Settings → Models and save a provider/model preset with your credential or supported sign-in. See model setup if you need the full steps.
2. Start a new topic and send Hello! to verify the model connection.
3. To try file work, put a copy of notes.txt in a practice folder, select that folder and Restricted access, and ask: "Read notes.txt and write a short summary to summary.md." Open summary.md in that folder to check the result. See Your first file task.

A normal reply verifies the provider/model and browser connection. The file task separately checks the selected project and its file permissions. Attaching a file sends it to the conversation; it does not change the selected project folder.

Then describe your next goal in the same chat, for example: "I am already using the WebUI. Help me connect Telegram and allow only my account." An enabled nanobot-document skill can consult the documentation bundled with your installation; see Continue with nanobot for examples, explicit invocation, and availability.

nanobot webui --no-open

ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@SERVER

nanobot onboard --wizard

nanobot -m "Hello!"

nanobot

/goal Review this project's tests and list the smallest missing test case.

nanobot gateway --background

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

nanobot gateway

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

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.

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. Start it with nanobot webui. WebUI access grants administration of the same agent instance; share it only with trusted operators. See Sharing access.

The screenshots below use example conversations, illustrative token counts, and paused schedules.

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 models in Settings, connect chat platforms in Channels, and manage Apps, Skills, and Automations.

Group up to four conversations and arrange them in columns, rows, a grid, or a main pane with supporting panes. Each topic keeps its own history. Select another topic from the @ menu, or drag it into the composer, to let the agent read its context and coordinate work across sessions.

Choose a project, access mode, and model for each task. Topics separate conversation history; project folders select where file work happens. Neither creates separate long-term memory: one instance shares its agent profile, memory, and skills across projects. Use separate instances when client data or preferences must stay isolated. Explore topics and panes →

Expand agent activity to see reasoning, tool calls, and file changes. Switch Settings → Appearance → File edit display to Diff for inline patches. The composer's context indicator shows the current context size, input tokens by round, and cache reuse when the provider reports it.

Context compaction also appears in the conversation timeline. Explore activity and context →

Use Apps to connect MCP servers, enable Agent Plugins, and manage local CLI App adapters. Add a preset or a custom server, then attach an available tool with @. Skills provide reusable instructions. Settings holds model, voice, image, and web setup; Channels handles chat-platform connections.

Explore Apps → · Discover Skills → · Connect chat apps →

Before connecting a personal bot to shared channels, check the platform's DM pairing/allowlist and group-access policies separately. Approving a private sender does not restrict group access on every platform; see the channel reference.

Ask for an automation from the topic that should receive its results. Use Tasks to review and manage schedules, or Calendar to scan completed and upcoming runs by date. Local triggers let a script start a saved task on demand.

Keep the gateway running and the host awake for scheduled delivery. Missed scheduled times are not replayed after a gateway restart. See delivery and recovery rules. Explore Automations →

For a conversation that should stay out of saved topic history and long-term memory, use Temporary chat from the header. Temporary chats end when the connection closes and use the default workspace in Restricted mode. Requests still go to the configured model provider, and files created by tools remain after the chat closes.

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.

The Python gateway owns agent execution, sessions, tools, memory, and security policy for the WebUI, TUI, and chat apps. The clients share that runtime; the core agent loop builds context, calls the model, executes requested tools, and returns the result. Memory, skills, channels, and MCP integrations extend that loop.

The Python SDK embeds the agent runtime in your application process. The OpenAI-compatible API starts a separate HTTP service for /v1/chat/completions: each request contains one user message, history is managed by the server, and the model comes from configuration. Responses return to the HTTP client; that service does not deliver tool messages to chat apps.

See Architecture for source ownership and extension points.

Browse the repo docs for current source documentation, or visit nanobot.wiki for the stable release. The task guide index groups walkthroughs by outcome.

• Get started: Beginner walkthrough or Install and Quick Start.
• Choose and configure a model: Providers and Models and Provider Cookbook.
• Connect a chat app: Chat App AI Agent and channel reference.
• Schedule or deploy work: Automations and Deployment.
• Integrate from code: Python SDK and OpenAI-Compatible API.
• Look up runtime concepts or exact settings: Concepts and Configuration.
• Diagnose a failure: Troubleshooting.
• Extend the core: Architecture and contribution workflow.

Latest release: v0.3.5

v0.3.5 brings the workbench to the terminal and makes conversations easier to continue across the browser, terminal, and chat apps.

• Use the native terminal workbench with the same gateway and saved conversations as the WebUI.
• Arrange up to four browser conversations side by side, mention saved sessions, or open a temporary chat.
• Inspect per-round context usage and compaction progress, with more durable history and recovery.
• Discover Skills, connect Apps, and manage scheduled work through expanded WebUI flows.

Read the v0.3.5 release notes and upgrade notes

• 2026-09-19 🔎 Searchable provider setup, consistent provider identities, and smoother Linear onboarding.
• 2026-09-18 ♻️ Clearer recovery for interrupted work and Discord reply-context support.
• 2026-09-16 📦 Platform wheels bundle the version-matched native terminal UI.
• 2026-09-15 🚀 Released v0.3.5 with a shared terminal workbench, multi-pane WebUI, and visible context continuity.
• 2026-09-07 🔌 WeCom media uploads use the SDK API, and CI skips unrelated jobs.

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

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.

Xubin Ren

Yongru Chen

Thanks for visiting ✨ nanobot!