nanobot

Ultra-lightweight, self-hosted personal AI agent runtime

nanobot is a self-hosted personal AI agent runtime. It keeps the agent core small and readable while providing the practical pieces for real, long-running work: a browser WebUI, chat channels, tools, memory, MCP, model routing, automation, and deployment.

This repository is a fork of the nanobot project, maintained by madkoding with production-focused additions for WhatsApp and the WebUI.

• Features
• What can nanobot do?
• Install
• Quick Start
• WebUI
• Architecture
• Documentation
• Differences from upstream
• Contributing
• License

• Persistent workflows — goals, memory, tools, and chat context survive long-running work.
• Chat-native reach — WebUI, API, Telegram, Feishu, Slack, Discord, Teams, email, Mattermost, WhatsApp, and more.
• 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.

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, WhatsApp, 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

Prerequisites: Python 3.11 or newer.

macOS / Linux:

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

Windows PowerShell:

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

The default command installs or upgrades this fork from its main branch on GitHub. On a fresh local desktop, it then starts nanobot webui so you can configure the first provider and model in Settings → Models. The installer avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv.

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

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

To install the published upstream release from PyPI instead, pass --pypi:

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

bun or npm must be available to build the WebUI. From an activated virtual environment:

git clone https://github.com/madkoding/nanobot.git
cd nanobot
python -m pip install .

Verify the install:

nanobot --version

Update nanobot to the latest main branch. The command detects your install (editable source checkout vs GitHub zip), updates the Python package, rebuilds the WebUI bundle, and restarts the gateway service automatically:

nanobot update

Check for updates without applying anything:

nanobot update --check

Useful flags:

• --yes / -y — skip confirmation prompts
• --no-restart — do not restart the gateway service
• --no-webui — skip the WebUI rebuild

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 the gateway, and opens http://127.0.0.1:8765. 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.

Keep nanobot running after you close the terminal

nanobot webui --background

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. Use nanobot gateway --background for the same direct entry point without keeping the terminal attached.

Prefer to work entirely in the terminal?

nanobot agent

This opens an interactive terminal chat with the same configured model, workspace, and tools. Type exit or press Ctrl+C when you are done.

For one request and an immediate exit:

nanobot agent -m "Hello!"

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

Use it to:

• keep separate topics for different tasks and projects;
• inspect reasoning, tool calls, file edits, diffs, command output, and generated artifacts;
• switch models and workspaces without leaving the conversation;
• configure providers, chat channels, Apps, Skills, and Automations from one place.

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.

Browse the repo docs for the latest features and GitHub development version.

• Guides — task-oriented guides
• Start Without Technical Background
• Install and Quick Start
• Concepts
• Architecture
• Providers and Models
• Provider Cookbook
• Troubleshooting
• Chat Apps
• Automations
• Configuration
• OpenAI-Compatible API · Python SDK
• Deployment

This fork builds on the upstream nanobot project and adds production-focused changes:

WhatsApp

• Per-group / per-sender context isolation with turn queuing and safe mentions
• Sender identity injection into agent context for group turns
• Contact display-name persistence and recall per chat
• Outbound allowlist to prevent bans when messaging unknown numbers
• Circuit-breaker for the WhatsApp 463 throttle with configurable cooldown
• Removed auto-reconnect — manual re-link only
• Outage prevention ("live but silent") with locks, watchdog, and persistence
• Typing indicator on the correct chat JID
• LID JID resolution in the outbound allowlist check

WebUI

• Live subagent panel (event hook + status TTL + HTTP/WS fan-out)
• Subagent spawn chips that open the live panel
• Automation chips + clickable markdown media
• Projects CRUD with chat binding and context injection
• Responsive layout for mobile (full-screen sidebar on phones, drawer on tablets, support ≤380px)

Core / tools

• Text-to-speech tool using edge-tts
• Native Gemma 4 tool-call and thinking-tag parsing
• Identity-separation guardrails + users.json template
• Gateway fix: foreground startup no longer aborts on its own pid

Docs / install

• Linux installer script and updated documentation links

PRs welcome! The codebase is intentionally small and readable. 🤗

See CONTRIBUTING.md for setup, review, and contribution guidelines.

Roadmap — pick an item and open a PR!

• Multi-modal — see and hear (images, voice, video)
• Long-term memory — never forget important context
• Better reasoning — multi-step planning and reflection
• More integrations — calendar and more
• Self-improvement — learn from feedback and mistakes

nanobot is released under the MIT License. Third-party notices are listed in THIRD_PARTY_NOTICES.md.