nanobot：把自架個人 AI Agent 變成可長駐的工作台
# nanobot: Turn your self-built personal AI Agent into a permanent workbench
If you want to put an AI Agent on your own computer or server, the real problem is usually not "can you call the model?" but how the model can connect to tools, remember context, continue to perform tasks, and be operated from a browser, terminal, or existing chat software. HKUDS/nanobot just converges these execution links into a Python project: it is a self-buildable personal AI Agent framework that provides WebUI, terminal and multiple chat channels, and puts tools, long-term memory, MCP, model routing, sub-agent and scheduling automation in the same runtime.
This article uses GitHub repository's README, `pyproject.toml` and official document links as the main sources of information to sort out nanobot's positioning, architecture, how to get started quickly, and which AI Chain development scenarios it is suitable for.
## First understand what problem nanobot solves
A general chatbot only needs to process "received message → text reply"; a permanent agent needs to process a longer life cycle:
- Receive jobs from WebUI, CLI or channels like Telegram, Discord, Slack, WeChat, Email, Mattermost and more.
- Let the model call file, shell, web search, web scraping, MCP, scheduling, image generation or subagent tools when needed.
- Save work session history and long-term memory so tasks don’t have to start from scratch every time.
- Leave long-term goals and periodic automation to the gateway for continuous execution.
- Allow other applications to integrate this Agent through Python SDK or OpenAI-compatible API.
The value of nanobot does not lie in wrapping another layer of chat UI, but in connecting "model decision-making" and "sustainable execution tool environment". This makes it closer to a self-serviceable Agent runtime than a single question and answer script.
## Core design: small Agent loop, plus pluggability
The official README describes the core of nanobot as a small agent loop: messages first come in from the chat channel, and LLM then determines whether tools need to be used; memories and skills are loaded as context when needed, instead of stacking all data into a huge orchestration layer.
This trade-off is suitable for developers who want to read, modify, or deploy Agents themselves. You can break the system down into easy-to-understand parts:
1. **Entrance and channel**: WebUI, terminal, chat platform and API are responsible for sending user work to the runtime.
1. **Model and routing**: You can set different providers, models and fallbacks, and you can also use OpenAI-compatible endpoint or local model services.
1. **Tool layer**: Capabilities such as files, Shell, search, MCP, cron, image generation and subagents are called by the model on demand.
1. **State and memory**: session history and long-term memory allow Agent to undertake multi-step work.
1. **Gateway and Deployment**: There are corresponding files for foreground or background execution, Docker, Docker Compose, Linux service and macOS LaunchAgent.
This structure also provides a clear expansion boundary: if you want to add a new chat channel, you can handle message adaptation first; if you want to connect to internal enterprise tools, you can start from MCP, Python SDK or OpenAI-compatible API.
## Get started quickly: first use WebUI to verify the complete link
It is officially recommended to use WebUI for the first time. The environment requirement is Python 3.11 or newer; the release package already contains WebUI. When installing from the current source code, you need `bun` or `npm` to build the front end. If using `uv`, you can install the CLI first:
```
uv tool install nanobot-ai
```
Then start the browser workbench:
```
nanobot webui
```
The first startup will create settings and workspace if needed, start the gateway, and open `http://127.0.0.1:8765`. After selecting provider, certificate and model in **Settings → Models**, create a topic and send `Hello!` to verify the connection. According to the official description, the initial WebUI is bound to localhost by default and will not be directly exposed to the local network; this is a safer default when verifying the settings on the local machine first.
After confirming that foreground mode is available, you can have the full gateway execute in the background:
```
nanobot webui --background
nanobot gateway status
nanobot gateway logs
```
If you only want to interact in the terminal, you can use:
```
nanobot agent
nanobot agent -m "Hello!"
```
`agent -m` is suitable for one-time provider checks, shell scripts or local automation; `gateway` is suitable for continuous operation of chat channels and schedules.
## From "being able to chat" to "being able to get work done"
The implementation potential of nanobot mainly comes from several capabilities that can be combined.
### 1. Tools and MCP
Agent not only generates text, but can also read and write files, execute Shell, search the network, retrieve web pages, or connect to external tools through MCP according to task needs. This allows it to move from "answering how to do it" to "complete a process within the scope of authorization." When deploying to a work environment, you should still set minimum permissions for the workspace, shell, and network tools first, and test high-risk operations separately.
### 2. Memory and long-term tasks
The README lists session history, long-term memory and Dream as part of the functionality. For research, content curation, project maintenance or periodic reporting, this is closer to the actual workflow than a single dialog window: tasks can retain context, and schedules can be started continuously in the gateway.
### 3. Multi-agent and model switching
The current release notes include inline subagents, per-session model switching, and more complete execution control. This means that a main Agent can hand over specific subtasks to helpers in the same work situation, or switch model defaults according to work needs; however, model switching and subagents do not automatically ensure correctness, and engineering rules still need to be established on prompts, tool permissions, output verification, and failure retries.
### 4. Chat channel and API integration
The WebUI is suitable for calling debugging and observation tools, the CLI is suitable for developers to quickly test, and the chat platform is suitable for bringing Agents into daily collaboration. To connect to existing services, you can also evaluate the Python SDK or OpenAI-compatible API instead of directly coupling internal modules.
## What situations are suitable for this?
nanobot is particularly suitable for the following situations:
- Want to deploy a personal AI assistant on your own hardware or server instead of handing all data to a hosting platform.
- Requires LLM to be connected to a file, command line, search, MCP or existing chat channel.
- Want to use WebUI to authenticate Agent first, and then use gateway, Docker or system service to persist.
- Requires session, long-term memory and scheduling to allow Agent to support multi-step or periodic work.
- Want to explore a relatively easy-to-read Python Agent runtime and customize providers, tools, or channels on top of it.
On the other hand, if the requirement is only a one-time model question and answer, and no tools and background execution are required, the gateway, channel and permission settings of nanobot may exceed the necessary scope.
## Three checkpoints before self-racking
**First, define the execution boundary. ** Shell, file and network tools give Agents real influence. Start with a dedicated workspace, limited accounts, and a clear whitelist of tools, rather than giving it access to the entire host as soon as you boot it up.
**Second, separate model setting and secret management. ** API key should not be written into articles, repositories or chat messages; use environment variables or dedicated secret management mechanisms when deploying, and confirm that the log will not echo sensitive values.
**Third, design observability for long-duration tasks. ** The WebUI can view reasoning, tool calls, file editing, diff, command output and products; for production environments, it is still recommended to retain gateway status, logs, failure notifications and manual approval points so that automation can be tracked and stopped.
## Conclusion
nanobot puts several key components of its own AI Agent into the same executable environment: WebUI and CLI are responsible for operation, gateway is responsible for persistence, tools and MCP are responsible for extending capabilities, memory and session are responsible for continuing context, and SDK and API are responsible for integrating other services. The most worthy of study is not that the feature list is long, but that it attempts to use a relatively small and readable Agent loop to take over the complete path from personal assistant to automated workflow.
To evaluate whether it is suitable for your team, it is recommended to first use the native WebUI to complete a low-risk task, and then gradually add MCP, chat channel, schedule and background gateway; for each added capability, simultaneously add permissions, logging and stopping mechanisms. Only in this way can the "calling model" be stably transformed into "the ability to complete work in one's own environment."
## Official information
- GitHub repository:
- Official README:
- Official documentation:
- Python package: