Nanobot AI

Overview

Nanobot AI is an open-source personal agent framework for running a lightweight agent across local CLI sessions, a browser WebUI, chat apps, MCP servers, CLI Apps, memory, cron, and long-running workspaces. It is not just a chatbot UI: the Python package exposes an agent runtime with channels, provider routing, workspace-aware tools, MCP integration, an OpenAI-compatible API surface, and deployment patterns for keeping the gateway online.

Use it when you want a self-hosted agent that can stay connected to your own tools and channels without adopting a large hosted automation platform. It is especially relevant for searches around personal AI agents, Claude-compatible workbenches, Codex/OpenAI provider routing, MCP-enabled agents, and chat-native agent deployment.

Install

Install the published Python package:

uv tool install nanobot-ai
nanobot --version

Initialize or refresh the local config and workspace:

nanobot onboard --wizard
nanobot status
nanobot agent -m "Hello!"

The upstream README also documents downloaded installer scripts for macOS, Linux, and Windows. Those are convenience paths, but they should be inspected before use. For agent and automation environments, prefer a package manager, virtual environment, or reviewed source checkout so the install path is clear.

Configuration Model

Nanobot stores its default config at ~/.nanobot/config.json and workspace state under ~/.nanobot/workspace/. The docs recommend proving a single local agent reply before enabling WebUI, chat channels, Docker, systemd, LaunchAgent, or custom tools.

Minimal production-oriented settings usually cover:

• Provider credentials through environment variables or a protected config file.
• A named model preset selected by agents.defaults.modelPreset.
• Workspace restriction for filesystem and shell-adjacent work.
• Explicit channel access control through allowFrom or pairing.
• Narrow MCP tool exposure with enabledTools when a server offers broad capabilities.

Capability Map

MCP and Agent Workflows

Nanobot treats MCP servers as native agent tools once they are configured under tools.mcpServers. Stdio servers use command, args, and optional env; remote servers use url and optional headers. HTTP and SSE MCP connections are checked by the shared SSRF guard before probing, before connecting, and again before following redirects.

For broad MCP servers, use enabledTools to keep the active tool surface small. The setting accepts raw MCP tool names such as read_file or Nanobot-wrapped names such as mcp_filesystem_read_file.

WebUI and Channels

The WebUI is served by the WebSocket channel after nanobot gateway starts. It adds session management, project workspace selection, visible agent activity, model settings, Apps, Skills, and automations around the same Nanobot runtime.

Chat channels use a common setup pattern: configure the channel credentials, keep access narrow with allowFrom or pairing, verify nanobot channels status, then run nanobot gateway --verbose while debugging startup. The docs call out that allowing everyone on a channel should only be used when that is intentional.

Security Boundaries

Nanobot has useful controls, but they need to be configured deliberately:

• tools.restrictToWorkspace keeps workspace-aware file tools under the active workspace and applies best-effort shell working-directory checks.
• tools.exec.sandbox: "bwrap" adds Linux bubblewrap isolation for shell commands and hides config files/API keys from the sandboxed process.
• tools.exec.enable: false removes the shell tool entirely.
• tools.ssrfWhitelist exempts private networks from the shared SSRF guard and should be kept as narrow as possible.
• Channel allowFrom and pairing determine who can send instructions into the agent.

Those controls matter because a long-running personal agent often has access to local files, project workspaces, chat credentials, model provider keys, and MCP tools at the same time.

Use Cases

• Run a local personal agent with persistent workspace, sessions, memory, and provider routing.
• Connect a Claude/OpenAI-compatible model workflow to MCP servers without manually wiring every tool into a separate host app.
• Keep an AI assistant online in Discord, Telegram, Slack, Matrix, Email, or a private WebUI while preserving explicit channel access controls.
• Operate long-running goals, cron automations, and workbench sessions from a self-hosted Python runtime.
• Expose a controlled OpenAI-compatible API for local experiments around one configured Nanobot instance.
• Compare lightweight self-hosted personal-agent stacks against larger agent platforms or hosted workflow automation tools.

Source Review

Verified on 2026-06-18:

• GitHub metadata reported HKUDS/nanobot as an MIT-licensed Python repository with the description Lightweight, open-source AI agent for your tools, chats, and workflows, a homepage at nanobot.wiki, active updates on 2026-06-18, latest release v0.2.1 published on 2026-06-01, and more than 44,000 stars.
• PyPI metadata for nanobot-ai reported version 0.2.1, summary A lightweight personal AI assistant framework, Python >=3.11, MIT license, and dependencies including Anthropic, OpenAI, MCP, web, channel, document, cron, and provider-related packages.
• The docs index says the repository docs track current source while published release documentation lives at nanobot.wiki, and points users through quick start, concepts, provider, WebUI, chat app, deployment, OpenAI API, Python SDK, and MCP configuration pages.
• The configuration docs document environment-variable secret placeholders, provider/model presets, channel settings, web tools, image generation, MCP servers, shell/workspace controls, SSRF whitelisting, pairing, and Langfuse observability.
• The MCP configuration section documents stdio and HTTP/SSE server config, optional headers, toolTimeout, enabledTools, and shared SSRF validation for remote MCP endpoints.
• The WebUI docs describe a packaged browser workbench with chat sessions, visible agent activity, workspace selection, Apps, MCP presets, Skills, Automations, settings, and WebSocket-channel serving.
• The chat-app docs document a common gateway-backed setup pattern and channel coverage across Telegram, Discord, WhatsApp, WeChat, Feishu, DingTalk, Slack, Matrix, Email, QQ, Napcat, WeCom, Microsoft Teams, Mochat, and Signal.
• The architecture docs map the runtime across channels, message bus, agent loop, provider/tool runner, tools, state, WebUI/gateway, memory, MCP, filesystem, shell, web, cron, image generation, and security boundaries.
• Release v0.2.1 describes WebUI workbench improvements, stronger long-running goal stability, unified CLI Apps and MCP extension workflows, broader provider routing, channel additions, and security/reliability hardening.