nanobot: From a Small Python Core to a Persistent Assistant
Purpose, mechanisms, getting started and boundaries
Source: HKUDS/nanobot · HKUDS
User Problem
Positioning and task fitnanobot is a self-hosted Python agent combining file tools, model calls, memory and channels. Current documentation includes a WebUI, terminal, sustained goals and automations, so an early small-codebase description is insufficient. Distinguish the shared runtime, sessions, project directories and instance memory to understand execution and persistence.
- Continue work through browser and terminal
- Integrate file work and scheduled tasks
- Study a Python agent’s message and tool loops
Product Mechanism
Capabilities and execution- A shared gatewayThe Python gateway owns execution, sessions, tools, memory and policy. WebUI, TUI and chat channels share that runtime, so closing one interface differs from stopping the service. Source
- Separate channel and model loopsAgentLoop owns session, workspace and channel-facing work; AgentRunner owns model and tool interaction. Misrouted messages and failed tool calls therefore have different starting points for investigation. Source
- Dream consolidates memoryPreferences can be consolidated into USER.md or memory files, with documentation recommending inspection of actual changes. Topics separate history, while one instance shares memory and skills across projects. Source
- Goals and scheduled workGoals continue work across model turns, while automations start work at scheduled times. Both need a running gateway, and background mode differs from an operating-system startup service. Source
Workflow
Start with a small task- Choose stable or sourceChoose stable release or current source deliberately, and do not infer installed features from source-branch screenshots. Prepare supported Python and model access.
- Configure through the WebUIRun nanobot webui, use the full printed login link and save a model in Settings. Treat that credential-bearing link as private.
- Run a file taskPut notes.txt in a practice directory, select workspace access and request summary.md. Inspect the real output file, distinguishing attachment upload from workspace selection.
- Verify persistenceCheck memory in a new session and inspect gateway status. For unattended use, configure a service and separately test restart and missed-schedule behavior.
The trial sequence and checks are editorial guidance. Entry commands follow official documentation; this project was not executed for the article. Source
Official entry example
nanobot webui
nanobot gateway statusComplete the prerequisites above first. Examples contain no real credentials.
Limits and Boundaries
Constraints and selection| Boundary | Meaning | Suggested action |
|---|---|---|
| Cross-project memory | Topics and project folders in one instance do not isolate long-term memory. Source | Use separate instances when client data or preferences need separation. |
| Missed schedules are not replayed | The documentation says missed scheduled times are not replayed after restart. Source | Check the last successful run and explicitly decide whether to recover missed work. |
Scroll horizontally to view the full table
It fits self-hosting users and Python developers studying channels and tool loops. Persistent operation still needs backups, updates and status checks.
How to Evaluate Adoption
Trial scenario and verificationA representative trial combines local document work and memory. Summarize one note, request that future summaries retain unresolved questions, inspect the consolidated memory and process another note in a new topic. Then close the client and inspect gateway lifetime. This tests tools, memory and lifecycle separately.
A normal reply checks model access, a file task checks permissions and tools, and preference reuse in a new topic checks memory. One hello response cannot establish all three.
Evidence: Pinned README · Supporting official documentation · Current repository。
Source fetched (UTC): 2026-11-02T07:26:43.677Z；snapshot commit: 8b37976d36c2。The source date denotes the repository snapshot commit, not the project’s original launch.