1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
|
uv tool install nanobot-ai
```
For users who want to isolate the CLI from system Python. Upgrading and uninstalling are also relatively clear and are the recommended paths for stable versions.
### pip
```bash
python -m pip install nanobot-ai
```
Should be executed in a virtual environment. Do not force install Python on your system, especially do not bypass `externally-managed-environment` with administrator privileges.
### Source code installation
The source code version has updated functions, but it may require `bun` or `npm` to build the WebUI, and the configuration and commands also change faster than the stable package. Only choose source code if you need the latest features or participate in development.
## What `onboard` will create
Run:
```bash
nanobot onboard --wizard
```
Mainly generated:
- `~/.nanobot/config.json`: Provider, model, agent and tool configuration;
- `~/.nanobot/workspace/`: Agent workspace, memory and related files.
After completing the wizard, first back up a configuration template that does not contain the real Key. When modifying the configuration in the future, use the merge method. Do not copy the entire JSON coverage wizard generated content in the tutorial.
## Detailed explanation of Provider and model presets
Configuration is usually divided into two levels:
```text
providers：怎样连接服务，包括 API Key 和 API Base
modelPresets：使用哪个 Provider、模型 ID 和参数
```
A conceptual example:
```json
{
"providers": {
"custom": {
"apiKey": "your-api-key",
"apiBase": "https://api.example.com/v1"
}
},
"modelPresets": {
"primary": {
"label": "Primary",
"provider": "custom",
"model": "model-id-from-your-provider",
"maxTokens": 8192,
"contextWindowTokens": 200000,
"temperature": 0.1
}
}
}
```
The real configuration should be merged into the existing file. `contextWindowTokens` cannot be written as a large value arbitrarily, and must be consistent with the actual model of the Provider, otherwise long tasks may fail on the server side.
## Five levels of first verification
### 1. Configuration status
```bash
nanobot status
```
Confirm Config, Workspace and current Provider. Displaying `not set` without a Provider does not indicate an error.
### 2. Single message
```bash
nanobot agent -m "只回复当前模型名称，不调用任何工具。"
```
Verify the model connection first. Do not open Shell, Search and MCP together.
### 3. Interactive session
```bash
nanobot agent
```
Check that multiple rounds of context, exit, and recovery are as expected.
### 4. WebUI
Start the Gateway and access `127.0.0.1:8765` to verify the session list, settings, and workspace without opening the LAN first.
### 5. A read-only tool
Finally add a read-only MCP or web tool and observe tool calls, logs and error handling. Don't consider write permissions until you're done.
## Don’t confuse WebUI and Gateway ports
Stable path:
```bash
nanobot gateway
```
Browser access:
```text
http://127.0.0.1:8765
```
`18790` is mainly a health check port, not WebUI. If the page cannot be opened, first check the Gateway log and `8765` listening status. Do not expose both ports to the public network.
To run in the background you can use:
```bash
nanobot gateway --background
nanobot gateway status
nanobot gateway logs
nanobot gateway restart
nanobot gateway stop
```
Before running for a long time, confirm the log location, automatic startup and abnormal exit recovery.
## Access Ollama’s check items
Ollama can be connected via a native OpenAI compatible interface, but at least check:
- Whether the API Base is accessible from the nanobot process;
- The model ID is consistent with `ollama list`;
- Whether the model can reliably support tool calls;
- Whether the context length configuration is true;
- Whether concurrency will exhaust video memory;
- Whether Gateway and Ollama only listen to trusted networks.
Test normal conversations first, then test individual tools. If a model returns a tool call that looks like JSON but is not in a valid format, the issue may be with model capabilities or template compatibility.
## How to authorize MCP Server in different levels
| Type | Initial Permissions Recommendations |
| --- | --- |
| Document query | Read-only, can be enabled first |
| Local files | Limited workspace, read-only start |
| Browser | Using Test Profile |
| Database | Read-only account and test library |
| Shell | Independent low-privilege environment |
| Cloud Platform | Minimal IAM, short-lived credentials |
Read the Server source code and tool list before installation. Commands, environment variables, and URLs appearing in an MCP configuration are considered part of the executable supply chain.
## What should be stored in long-term memory?
Memory is suitable for saving stable preferences, project commitments, and information that the user explicitly requests to retain. It is not suitable for automatic saving:
- API Key and password;
- One-time verification code;
- Customer original data;
- Unconfirmed model inference;
- Large sections of content that can be re-read from the project file;
- Expired temporary task status.
After activation, regularly check the memory files to confirm that the deletion and correction mechanism is effective. Long-term memory errors are repeatedly amplified in subsequent tasks.
## Chat application access sequence
First use a test bot and a whitelist account that only allows yourself, and then open the group chat. Each channel needs to be confirmed:
1. Who can send messages to the robot;
2. Whether group members can trigger the tool;
3. Where are the attachments saved?
4. Whether to echo the internal log;
5. Who creates and cancels scheduled tasks;
6. How to restore the robot after it is offline;
7. Whether the chat platform keeps copies of messages.
Chat convenience is not a substitute for identity and permission control.
## Scheduled automated security rules
Long-term goals and cron tasks should have:
- Clarify the operating frequency;
- Maximum execution time;
- Maximum model fee;
- Limit on the number of tool calls;
- Idempotent or deduplication mechanism;
- Failure notification;
- Manual stop switch;
- Do not use infinite retries.
Only do read-only summarization when you first create the automation, and then allow writing of files or sending messages after a few rounds of observation.
## Public network deployment checklist
If you must access the WebUI through the server:
- Set strong random `NANOBOT_WEB_TOKEN`;
- Use HTTPS reverse proxy;
- Only expose necessary ports;
- Restrict source IP or use VPN;
- Persistent configuration, workspace and memory;
- Do not write the Key into the image;
- Restrict container permissions and mounting;
- Configure log rotation and backup;
- Record versions and test recovery before upgrading.
One-click deployments for platforms like Render also require persistent disks, otherwise sessions and memory may be lost with instance rebuilds.
## Troubleshooting Matrix
| Phenomenon | Common causes | Treatment methods |
| --- | --- | --- |
| `nanobot` not found | Tools directory not in PATH | Use `uv tool run` or fix PATH |
| 401 | Key or Provider configuration error | Check `providers` |
| 404 Model does not exist | Model ID or API Base does not match | Check server model list |
| WebUI cannot be opened | Port confusion or Gateway not started | Check 8765 and logs |
| Tool call format error | Model is not supported or template is incompatible | Replace the model that supports the tool |
| Session disappeared after restart | Workspace not persisted | Check disk and mount |
| Chatbot unresponsive | Token, whitelist or gateway | Hierarchical inspection channel logs |
| Repeated execution of scheduled tasks | Lack of idempotence and status records | Add deduplication keys and execution locks |
## FAQ
### What should I do if `nanobot` is not in PATH?
Use the startup command corresponding to the installation method, for example:
```bash
uv tool run --from nanobot-ai nanobot --version
```
You can also check whether `uv tool` or the executable directory of the virtual environment has been added to `PATH`.
### WebUI cannot be opened but health check is normal
The default port of WebUI is `8765`; the `18790` port of Gateway is mainly used for health check, not the browser interface. Confirm the actual listening address and error log in the terminal.
### Can I pick up Ollama directly?
Can be configured via the native OpenAI compatible interface, but verify that the model supports the required tool call format, context length, and concurrency. The success of ordinary conversations does not mean that MCP and complex tool calls are necessarily stable.
### What is the difference between `nanobot webui` and `nanobot gateway`?
Stable releases prefer to use `gateway` and open the page manually; newer source code versions may provide the `webui` command to automatically prepare the channel and open the browser. The help information of the currently installed version shall prevail.
### Can multiple people share the same nanobot?
Need to verify that user, session, workspace and tool permissions are truly isolated. Use it as a single-user Agent before confirming, and do not rely solely on chat nicknames to distinguish permissions.
### How to back up?
Back up `~/.nanobot/config.json`'s security templates, workspaces, memories, and necessary session data. The real Key is best re-injected by Key Management and not entered into a normal backup.
### What should I do if the configuration fails after updating?
First check the version changes and migration instructions, use backup to restore, and then merge the configurations one by one. Do not overwrite the default structure generated by the new version with the entire section of the old file.
## Summary
The advantage of nanobot is that it has a smaller core and also has WebUI, memory, MCP, automation and chat portal. The most secure deployment method is to start from the local terminal, open functions and network scopes layer by layer, and set permission boundaries for tools, chat channels, and long-term memory.
|