NanoBot Setup Guide: GLM-5.3 & MiniMax M3.1 on Your VPS
Nanobot v0.4 setup guide: install nanobot on a VPS with GLM-5.3 and MiniMax M3.1 Flash, add the WebUI, Discord, web search, Docker or systemd, for ~$5/month.
Updated Published 35 min read

Disclosure: this guide contains referral links. If you buy through them, I may earn a commission at no extra cost to you.
This nanobot setup guide walks through installing nanobot v0.4.0 on a VPS with GLM-5.3 and MiniMax M3.1 Flash as your models. nanobot is an open-source AI assistant from HKUDS that runs on your server and talks to you through Discord, Telegram, Slack, or a dozen other chat apps. Since I first covered it at v0.1, it has grown a bundled WebUI, a native TUI, model presets with fallback chains, Docker Compose support, and roughly 40 LLM providers. The total cost for a personal setup is around $5-15/month for the VPS plus API usage.
NanoBot GitHubWhat this guide covers
- Install nanobot via the official script, uv, pip, or Docker
- Configure GLM-5.3 and MiniMax M3.1 Flash as LLM providers
- Model presets, fallback chains, and runtime switching
- Web search: DuckDuckGo by default, Brave Search optional
- Discord integration and the nanobot WebUI (port 8765)
- Docker Compose, systemd service, Automations, and security hardening
- Troubleshooting table for common first-run failures
If you’re comparing self-hosted bot options, our OpenClaw alternatives roundup covers nanobot alongside NanoClaw, memU, PicoClaw, and others. For MCP basics, check the MCP introduction for beginners.
Model change since this video
The walkthrough above was recorded on nanobot v0.1.x with MiniMax M2.5 and GLM-5. Those models are being retired or superseded. This guide has been updated for nanobot v0.4.0 with GLM-5.3 and MiniMax M3.1 Flash. The Discord setup steps in the video are still accurate.
What is nanobot? What’s new in v0.4.0
nanobot is an open-source project from HKUDS (University of Hong Kong). It’s an AI assistant that runs on your server and connects to whatever chat app you prefer. The core is still a small, readable Python codebase, but v0.4.0 (released 2026-10-28) added a full admin surface: a bundled WebUI, a native terminal UI, a Python SDK, and an OpenAI-compatible API.
The architecture has not changed:
You (Discord / Telegram / WhatsApp / Slack / etc.)
↓
nanobot Gateway (running on your VPS)
↓
LLM Provider (GLM-5.3, MiniMax M3.1 Flash, Ollama, OpenRouter, etc.)
↓
Tools (file access, shell commands, web search, MCP servers)Messages come in from your chat app, nanobot routes them to your configured LLM, and the model can use tools to get things done. Everything except the LLM API calls stays on your machine.
Here’s what’s new since the v0.1 days:
| Feature | What it does |
|---|---|
WebUI (nanobot webui) |
Browser admin panel on port 8765: providers, models, Apps (MCP), Tasks/Calendar |
Native TUI (nanobot) |
Full terminal interface, not just nanobot agent |
| Model presets | Named model configs with fallbackModels chains |
| SQLite history | Session history stored in a database, not loose files |
| Docker Compose | One-command deployment with health checks and hardened defaults |
| systemd integration | nanobot gateway install-service generates and installs a user service |
| Automations | Scheduled tasks managed in the WebUI, replacing the old cron CLI |
| ~40 providers | GLM, MiniMax, OpenRouter, Anthropic, Bedrock, local Ollama/vLLM, and more |
| Voice transcription | Built in, Groq as default provider |
Why GLM-5.3 and MiniMax M3.1 Flash for a self-hosted bot
For an always-on bot, you want models that are cheap per token, have large context windows, and are good at tool use. Both cost $0.15/M input tokens and give you 1M-token contexts. That means nanobot won’t hit context limits even with long conversations and big files loaded.
For more options in this price range, see the cheapest AI models for agents under $1/M tokens and best open source models for OpenClaw.
MiniMax M2.5 is being retired on 2026-11-18
If your config still points at MiniMax-M2.5, it stops working on 2026-11-18. New users have been blocked from M2.5 since 2026-10-19. M Plan and Token Plan requests to M2.5 are already auto-routed to M3.1 Flash. Update your config to MiniMax-M3.1-Flash now. This is the main reason this guide got a rewrite.
GLM-4.7-Flash is free if you want to test the pipeline with zero API cost before committing.
GLM-5.3 and GLM-5.3-Flash: specs and pricing
GLM-5.3 is Zhipu’s current flagship. GLM-5.3-Flash is the cheap, fast variant that makes the most sense for a chat bot:
| Spec | GLM-5.3 | GLM-5.3-Flash |
|---|---|---|
| Architecture | Text-only, same base as GLM-5.2 | 320B total, 18B active |
| Context window | 1M tokens | 1M tokens |
| Max output | 128K tokens | 128K tokens |
| Input cost | $1.40/M tokens | $0.15/M tokens |
| Output cost | $4.40/M tokens | $0.50/M tokens |
| Cached input | $0.26/M tokens | - |
| Reasoning | Always on (reasoning_effort: low/high/max) |
Always on |
| License | MIT | MIT |
GLM-5.3 is always reasoning now. Disabling reasoning fails requests. If you’re migrating from older GLM configs, set thinking.type: "enabled" and reasoning_effort: "low" to keep costs down. GLM-5.3-Flash uses sparse and linear attention for roughly 3x attention efficiency versus 5.3. There’s also GLM-5.3-FlashX at $0.37/$1.25 if you need 200 tokens/sec. For heavy use, the Z.AI GLM Coding Plan starts at $18/month.
The efficiency and throughput numbers above are vendor-published by Z.ai.
The older GLM-5 is still listed at $1.0/$3.2 per M tokens but is superseded. Don’t start new configs on it.
MiniMax M3.1 Flash: specs and pricing
MiniMax M3.1 Flash is the replacement for M2.5 and the obvious pairing with GLM-5.3-Flash:
| Spec | Value |
|---|---|
| Context window | 1M tokens |
| Input cost | $0.15/M tokens |
| Output cost | $0.60/M tokens |
| Cache read | $0.015/M tokens |
| Thinking depth | Tunable via effort parameter |
The effort parameter lets you dial thinking depth up or down depending on the task. For a chat bot, low effort is usually fine and keeps latency low.
MiniMax also offers MiniMax-M3, a multimodal coding model at $0.30/$1.20 (standard tier, ≤512k input, permanent 50% discount) or $0.60/$2.40 above 512k. Worth it if your bot does coding work. Both models run on MiniMax’s global platform (platform.minimax.io) and mainland China platform (minimaxi.com).
Install nanobot on your VPS
nanobot requires Python 3.11+. Wheels cover Linux x64/ARM64 (glibc 2.17+), Windows, and Python 3.14.
Official script (recommended)
The fastest path. The script installs nanobot and launches the setup wizard:
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | bashOn Windows, use install.ps1 instead. After installation, verify:
nanobot --versionuv or pip
If you prefer managing Python packages yourself:
# With uv (recommended - faster, isolated)
uv tool install nanobot-ai
# Or with pip
pip install nanobot-aiIf you don’t have uv yet, see getting started with uv. Verify:
nanobot --versionFrom source
For the latest features or if you plan to modify the code. Requires Git, Python 3.11+, and Bun (serves the TUI from the checkout):
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install -e .Verify:
nanobot --versionAfter installing, initialize the workspace and config:
nanobot onboardThis creates ~/.nanobot/ with a config.json and a workspace/ folder for memory, skills, and bootstrap files.
First run: onboarding and the nanobot WebUI
nanobot v0.4.0 gives you two first-run paths: a terminal wizard or the browser WebUI. Both create the same ~/.nanobot/config.json and workspace/ structure.
The WebUI is full admin access
Anyone with WebUI access can change models, read memory files, and run tools. Do not expose port 8765 to the internet. Use an SSH tunnel or a mesh VPN like Headscale to reach it remotely.
Set up with nanobot onboard --wizard
The terminal-only path. Interactive prompts walk you through provider selection, API keys, and channel setup:
nanobot onboard --wizardTo refresh config non-interactively after editing config.json by hand:
nanobot onboard --refreshVerify everything is wired up:
nanobot statusThis prints a config/workspace summary and validates your active provider and model. If the provider key is wrong or missing, it tells you here.
Browser setup with nanobot webui (port 8765)
The WebUI is the new recommended way to set up nanobot. It walks you through providers, model presets, MCP apps, and scheduled tasks in the browser:
nanobot webuiThis opens http://127.0.0.1:8765 and prints a login link with a # credential fragment. Useful flags:
--no-open- don’t auto-open the browser (useful on a headless VPS)--detach- run the WebUI in the background
For a remote VPS, tunnel the port over SSH:
ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@YOUR_SERVER_IPThen open http://127.0.0.1:8765 in your local browser. You can also set NANOBOT_WEB_TOKEN to require a login token.
From the WebUI you can manage providers, switch model presets, install MCP apps from a preset catalog, and view Tasks/Calendar for Automations.
Configure MiniMax M3.1 Flash
The config lives at ~/.nanobot/config.json. Use environment variable references for secrets so API keys never land in plaintext config files.
Get a MiniMax API key
- Go to platform.minimax.io (global) or minimaxi.com (mainland China)
- Create an account and generate an API key
- Note which platform you’re on, because the API base URL differs
M3.1-Flash is available to all users. M2.5 is not (new users blocked since 2026-10-19).
MiniMax coding plan
MiniMax offers coding plans priced for developer workloads. Get 10% off with our referral link. If you want to use GLM and MiniMax models with the Codex app, the same API keys work there too.
Export the key so nanobot can resolve it:
export MINIMAX_API_KEY="your-minimax-api-key"Add it to ~/.bashrc or ~/.profile to persist across sessions.
Add MiniMax to config
For the global platform:
{
"providers": {
"minimax": {
"apiKey": "${MINIMAX_API_KEY}"
}
},
"modelPresets": {
"minimax-flash": {
"provider": "minimax",
"model": "MiniMax-M3.1-Flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
}
},
"agents": {
"defaults": {
"modelPreset": "minimax-flash"
}
}
}For the mainland China platform, add the apiBase override:
{
"providers": {
"minimax": {
"apiKey": "${MINIMAX_API_KEY}",
"apiBase": "https://api.minimaxi.com/v1"
}
}
}The ${MINIMAX_API_KEY} syntax is resolved from the environment at startup and never written back to the config file. Test it:
nanobot -m "What's 42 * 17?"If you get a response, MiniMax is wired up correctly.
Thinking mode with the minimaxAnthropic provider
If you want tunable thinking depth (reasoningEffort), use MiniMax’s Anthropic-compatible endpoint via the minimaxAnthropic provider:
{
"providers": {
"minimaxAnthropic": {
"apiKey": "${MINIMAX_API_KEY}",
"apiBase": "https://api.minimax.io/anthropic"
}
}
}For mainland China, the endpoint is https://api.minimaxi.com/anthropic. Same API key works for both.
Configure GLM-5.3 (Zhipu / Z.AI)
GLM-5.3 goes through Zhipu’s API. nanobot has built-in support.
Get a Zhipu API key
- Go to z.ai
- Register and create an API key
Z.AI GLM coding plan
Z.AI offers GLM coding plans from $18/month designed for continuous developer workloads. Use our link for 10% off. The coding plan is worth it if your bot handles heavy coding tasks daily.
Export the key:
export ZHIPU_API_KEY="your-zhipu-api-key"Add GLM-5.3 to config
{
"providers": {
"zhipu": {
"apiKey": "${ZHIPU_API_KEY}"
}
},
"modelPresets": {
"glm-flash": {
"provider": "zhipu",
"model": "glm-5.3-flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
}
},
"agents": {
"defaults": {
"modelPreset": "glm-flash"
}
}
}If you’re on Zhipu’s mainland coding plan, set the API base to the coding endpoint:
{
"providers": {
"zhipu": {
"apiKey": "${ZHIPU_API_KEY}",
"apiBase": "https://open.bigmodel.cn/api/coding/paas/v4"
}
}
}International coding endpoint
The international api.z.ai coding endpoint (https://api.z.ai/api/coding/paas/v4) is not currently documented in nanobot’s provider docs. Test it with your key before relying on it. The mainland open.bigmodel.cn endpoint above is the documented path.
Test:
nanobot -m "Hello!"If you want to use GLM and MiniMax models with the Codex app as well, the same Zhipu API key works across tools.
Model presets and fallback models
nanobot v0.4.0 uses modelPresets for named model configurations. Each preset pins a provider, model name, token limits, and context window. The old agents.defaults.model syntax still works (it becomes an implicit default preset), so existing configs don’t break.
Here’s the recommended setup with two presets and a fallback chain:
{
"providers": {
"zhipu": { "apiKey": "${ZHIPU_API_KEY}" },
"minimax": { "apiKey": "${MINIMAX_API_KEY}" }
},
"modelPresets": {
"fast": {
"provider": "zhipu",
"model": "glm-5.3-flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
},
"deep": {
"provider": "minimax",
"model": "MiniMax-M3.1-Flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
}
},
"agents": {
"defaults": {
"modelPreset": "fast",
"fallbackModels": ["deep"]
}
}
}The fallbackModels array means: if the primary preset fails (rate limit, provider down, auth error), nanobot tries the next one. For maximum resilience, add a local Ollama fallback:
{
"modelPresets": {
"ollama": {
"provider": "ollama",
"model": "qwen3:8b",
"contextWindowTokens": 32000
}
},
"agents": {
"defaults": {
"modelPreset": "fast",
"fallbackModels": ["deep", "ollama"]
}
}
}Note the smallest-context-window rule: nanobot builds context to the smallest window in your chain, so a 32K local model will cap things at 32K even if your primary is 1M. If you want local models for fallback, the best mini PC for local LLMs and Ollama covers the hardware side. For installing Ollama itself, see installing Ollama with Docker. Both ollama (http://localhost:11434/v1) and vllm are built-in local providers.
At runtime, switch presets with /model <name> in chat. Pin "provider" in every preset. Don’t rely on model name matching to route to the right provider - that’s the most common source of “model not found” errors.
Web search: DuckDuckGo by default, Brave Search optional
Since v0.3.x, nanobot’s default web search is DuckDuckGo. It’s free, needs no API key, and works out of the box. If you don’t configure anything, your bot can already search the web.
If you want better results or more control, Brave Search is the upgrade. Just know that Brave moved from subscriptions to prepaid credits (up to $20/month free).
Get a Brave Search API key
- Go to brave.com/search/api
- Sign up for an account
- The free tier gives you up to $20 in prepaid credits per month (no subscription)
- Generate an API key from the dashboard
Enable Brave in config
{
"tools": {
"web": {
"search": {
"provider": "brave",
"apiKey": "${BRAVE_API_KEY}",
"maxResults": 5
}
}
}
}Export the key:
export BRAVE_API_KEY="your-brave-search-api-key"The `provider` field is required
Without "provider": "brave" in the config, nanobot silently falls back to DuckDuckGo even if you set a Brave API key. This trips up everyone migrating from the old config format. If you want DuckDuckGo, just omit the whole tools.web.search block.
maxResults controls how many results nanobot pulls per search (default 5, range 1-10). Other built-in search providers: tavily, jina (10M-token free tier), kagi, olostep, bocha, volcengine, keenable (free), and searxng (self-hosted).
Discord setup
Discord works well for personal and team bot setups. The steps below match nanobot’s official docs and haven’t changed since v0.1.
Create a Discord bot
- Go to discord.com/developers/applications
- Click New Application, give it a name
- Go to Bot in the left sidebar, click Add Bot
- Copy the bot token
Enable intents
Still in the Bot settings page:
- Scroll down to Privileged Gateway Intents
- Enable MESSAGE CONTENT INTENT (required, or the bot can’t read messages)
- Optionally enable SERVER MEMBERS INTENT if you plan to use allow lists
Get your user ID
- Open Discord Settings, go to Advanced, enable Developer Mode
- Right-click your avatar anywhere in Discord
- Click Copy User ID
Configure nanobot
{
"channels": {
"discord": {
"enabled": true,
"token": "${DISCORD_BOT_TOKEN}",
"allowFrom": ["YOUR_USER_ID"],
"allowChannels": [],
"groupPolicy": "mention",
"streaming": true,
"replyToMessage": false
}
}
}Export the bot token:
export DISCORD_BOT_TOKEN="your-discord-bot-token"Field breakdown:
allowFrom- restricts who can talk to the bot. Empty array = anyone. Add user IDs to lock it down. For a personal bot, always set this.allowChannels- restrict which channels the bot responds in. Empty = all channels.groupPolicy-"mention"(default) means the bot only responds in group channels when @mentioned. DMs always work.streaming- streams responses token by token instead of waiting for the full reply.replyToMessage- replies to the specific message instead of sending a new one.
Invite the bot to your server
- In the Discord developer portal, go to OAuth2 then URL Generator
- Under Scopes, check
bot - Under Bot Permissions, check
Send MessagesandRead Message History - Copy the generated URL and open it in your browser
- Select the server you want to add the bot to
Start the gateway and verify
For a quick test:
nanobot gatewaySend the bot a DM in Discord. It should respond. If nothing happens, check nanobot status and look at the gateway logs. For production use, set up a systemd service (see the systemd section below).
Full config example (v0.4)
Here’s a complete ~/.nanobot/config.json with GLM-5.3-Flash as primary, MiniMax M3.1 Flash as fallback, Brave Search, Discord, and security hardening:
{
"providers": {
"zhipu": {
"apiKey": "${ZHIPU_API_KEY}"
},
"minimax": {
"apiKey": "${MINIMAX_API_KEY}"
}
},
"modelPresets": {
"fast": {
"provider": "zhipu",
"model": "glm-5.3-flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
},
"deep": {
"provider": "minimax",
"model": "MiniMax-M3.1-Flash",
"maxTokens": 8192,
"contextWindowTokens": 1000000
}
},
"agents": {
"defaults": {
"modelPreset": "fast",
"fallbackModels": ["deep"],
"workspace": "~/.nanobot/workspace"
}
},
"channels": {
"discord": {
"enabled": true,
"token": "${DISCORD_BOT_TOKEN}",
"allowFrom": ["YOUR_USER_ID"],
"allowChannels": [],
"groupPolicy": "mention",
"streaming": true
}
},
"tools": {
"web": {
"search": {
"provider": "brave",
"apiKey": "${BRAVE_API_KEY}",
"maxResults": 5
}
},
"exec": {
"maxRuntime": 60,
"sandbox": "bwrap"
},
"restrictToWorkspace": true
},
"gateway": {
"host": "127.0.0.1",
"port": 18790
}
}Config settings explained
| Setting | Default | What it does |
|---|---|---|
modelPresets.<name>.provider |
- | Which provider adapter to use (pin this, don’t rely on name matching) |
modelPresets.<name>.model |
- | Model ID sent to the provider |
modelPresets.<name>.contextWindowTokens |
varies | Context window size; AutoCompact triggers before this limit |
agents.defaults.modelPreset |
default |
Which preset to use by default |
agents.defaults.fallbackModels |
[] |
Preset names to try if the primary fails |
agents.defaults.workspace |
~/.nanobot/workspace |
Where memory, skills, and bootstrap files live |
tools.exec.maxRuntime |
3600 |
Hard runtime limit for shell commands in seconds (tools.exec.timeout is a legacy alias) |
tools.exec.sandbox |
none | Process-level shell isolation: "bwrap" (Linux) or "seatbelt" (macOS) |
tools.restrictToWorkspace |
false |
When true, file/shell access is limited to the workspace |
tools.web.search.provider |
duckduckgo |
Web search provider |
gateway.host |
127.0.0.1 |
Bind address. Use 0.0.0.0 only with auth configured |
gateway.port |
18790 |
Gateway port |
Context is managed automatically now: AutoCompact handles token limits and Dream handles memory consolidation. The old maxToolIterations and memoryWindow settings are gone from the config reference.
Memory system and workspace files
nanobot stores long-term memory in two files inside the workspace:
| File | Purpose |
|---|---|
~/.nanobot/workspace/memory/MEMORY.md |
Long-term facts the bot remembers |
~/.nanobot/workspace/memory/USER.md |
Your personal info and preferences (consolidation target) |
Tell the bot to remember something and it writes to MEMORY.md. The Dream system (/compact, /dream, /dream-log) consolidates conversation history into these files periodically. Session history itself lives in SQLite since v0.4.0.
Workspace bootstrap files
The workspace also has bootstrap files that shape how the bot behaves:
| File | Purpose |
|---|---|
AGENTS.md |
Agent configuration and instructions |
SOUL.md |
Personality and behavior rules |
USER.md |
Your personal info and preferences |
TOOLS.md |
Tool usage instructions |
IDENTITY.md |
Bot identity overrides |
These get loaded into the system prompt every time the bot processes a message. Edit USER.md to tell the bot about yourself:
nano ~/.nanobot/workspace/USER.mdAdd whatever context you want the bot to always have. Project details, preferred communication style, technical preferences. Edit SOUL.md to change how it communicates.
MCP support
nanobot supports Model Context Protocol for connecting external tool servers. The config format is the same as Claude Desktop and Cursor, so you can copy MCP server configs from any MCP server’s README. Since v0.4.0, MCP servers are also manageable through the Apps section in the WebUI with a preset catalog.
Adding an MCP server
{
"tools": {
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
}
}
}
}Two transport modes work:
| Mode | Config fields | Example |
|---|---|---|
| Stdio | command + args |
Local process via npx or uvx |
| HTTP | url |
Remote endpoint like https://mcp.example.com/sse |
MCP tools get discovered and registered automatically when nanobot starts. For connecting to 1,500+ apps via MCP, see the Composio MCP guide to connect 1,500+ apps.
Docker deployment with Docker Compose
Docker Compose is the documented happy path for containerized nanobot. There’s no official registry image; you build from the repo.
Docker bind gotcha - the #1 failure
The gateway binds to 127.0.0.1 by default. Docker’s -p flag cannot reach a container’s loopback interface. For published ports, you must set gateway.host to 0.0.0.0 in config.json AND configure a token, tokenIssueSecret, or trustedProxyAuth - nanobot refuses to start WebSocket on 0.0.0.0 without auth. This is why it “works locally but not in Docker.” Also note why Docker bypasses UFW firewall rules.
Quick start with Docker Compose
git clone https://github.com/HKUDS/nanobot.git && cd nanobot
docker compose up -d
docker compose logsFirst boot initializes config with container bind addresses and random WebUI credentials. The password is printed in the logs. Open http://YOUR_HOST:8765 and set up your provider in Settings.
The data mount is ~/.nanobot:/home/nanobot/.nanobot (the container runs as UID 1000, not root - don’t use /root/.nanobot).
Verify:
curl --fail http://127.0.0.1:18790/healthThe health endpoint should return 200. Publish it to host loopback only, not to the internet.
Manual docker build and run
If you don’t want Compose:
# Build
docker build -t nanobot .
# Run with your config mounted
docker run -d \
-v ~/.nanobot:/home/nanobot/.nanobot \
-p 127.0.0.1:18790:18790 \
--name nanobot \
nanobot gatewayBuild args let you bundle specific channels and extras: NANOBOT_CHANNELS=telegram,slack, NANOBOT_EXTRAS=bedrock. Don’t use third-party Docker images for nanobot; the docs explicitly mark them as untrusted.
The Compose setup includes hardened defaults (capability drop, no-new-privileges) and an optional bwrap sandbox override.
Run nanobot as a systemd service
For 24/7 operation, use nanobot’s built-in service installer. It generates and installs a systemd user service:
nanobot gateway install-service --manager systemdThis creates ~/.config/systemd/user/nanobot-gateway.service, enables it, and starts it. Preview without installing:
nanobot gateway install-service --manager systemd --dry-runManage the service:
systemctl --user status nanobot-gateway
systemctl --user restart nanobot-gateway
journalctl --user -u nanobot-gateway -fTo keep user services alive after you log out:
loginctl enable-linger $USERFor multi-instance setups (personal bot + team bot), use --name, --config, and --workspace flags. Uninstall with nanobot gateway uninstall-service --manager systemd.
Why the old unit file approach fails
Hand-written unit files with ExecStart=/usr/local/bin/nanobot gateway break on uv tool installs (the binary lives in ~/.local/bin/) and run without the user environment. The built-in installer handles the paths and environment correctly.
For a lighter alternative to systemd, use the built-in daemon mode:
nanobot gateway --background
nanobot gateway stop
nanobot gateway restartAutomations: scheduled tasks and /goal
The nanobot cron add/list/remove commands from v0.1 are no longer in the CLI reference. Scheduling is now handled by Automations, managed in the WebUI’s Tasks/Calendar views.
To create an automation, just ask the bot in a conversation: “Every morning at 9am, check my server disk usage and send me a summary.” The bot creates the schedule and it shows up in the WebUI where you can pause, resume, rename, or edit it.
For local triggers (CI pipelines, webhooks, shell scripts), create the trigger in the chat or WebUI topic where the results should land:
/trigger PR reviewnanobot replies with a trigger ID and a ready-to-copy command:
nanobot trigger trg_8K4P2Q9X "Review PR #4502"Run that command from your script, webhook, or CI job to push a message into the session. If you run multiple nanobot instances, pass the matching --config or --workspace option so the trigger hits the right one. The agent also has a cron tool it can use for self-scheduled tasks.
/goal handles long-running tasks: give it a multi-step objective and it works through it over time.
Heartbeat is enabled by default on the gateway (gateway.heartbeat.enabled). It checks HEARTBEAT.md in your workspace for periodic tasks.
Missed schedules are not replayed
If the gateway restarts, missed automation schedules are not replayed. Don’t rely on Automations for billing-critical jobs without external monitoring.
Security hardening
The basics matter more than exotic configurations. Here’s what to set up:
Workspace restriction and sandbox
{
"tools": {
"restrictToWorkspace": true,
"exec": {
"sandbox": "bwrap"
}
}
}restrictToWorkspace limits file and shell access to ~/.nanobot/workspace/. It’s an application-level guard. For actual process-level isolation, add exec.sandbox: "bwrap" (Linux) or "seatbelt" (macOS). Use both.
Environment variable secrets
Never put API keys in plaintext config. Use the ${VAR_NAME} syntax:
{
"providers": {
"zhipu": { "apiKey": "${ZHIPU_API_KEY}" }
}
}These are resolved from the environment at startup and never written back to the config file.
Channel access control
Use allowFrom (user IDs) and allowChannels (channel IDs) to restrict who can talk to the bot. groupPolicy: "mention" (the default) means the bot only responds in group chats when @mentioned.
WebUI security
Don’t expose port 8765. Use an SSH tunnel or a mesh VPN. If you need LAN access, set NANOBOT_WEB_TOKEN or configure trustedProxyAuth.
Network-level
If you’re running on a VPS with Docker, read how I secured my Hetzner Docker server for firewall and network hardening that applies here too. tools.ssrfWhitelist lets you restrict which URLs the bot’s web fetch tool can reach.
Verify your setup (quick checklist)
After setup, run through this:
nanobot –version- confirms the installnanobot status- validates provider/model confignanobot -m “Hello!”- confirms LLM connectivitycurl –fail http://127.0.0.1:18790/health- gateway is up- Send a Discord DM and confirm a reply
journalctl –user -u nanobot-gateway -fordocker compose logs -f- check for errors
If all six pass, you’re done.
Troubleshooting common nanobot errors
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | API key missing, has whitespace, or wrong provider | Check providers.<name>.apiKey; verify env vars are exported (echo $MINIMAX_API_KEY) |
| “model not found” | Wrong model ID for the provider | Check the provider’s model list; pin provider in the preset |
| Connection refused | Local server down or wrong apiBase port |
Check apiBase URL; confirm Ollama/vLLM is running |
| Works in CLI but not chat | Gateway or channel issue | Check nanobot status, channel logs, allowFrom/allowChannels |
| Mixed provider + model key | Most common first-run failure - API key from one provider with model ID from another | Match the key to the provider that serves that model |
| WebUI won’t load in Docker | Gateway bound to 127.0.0.1, -p can’t reach it |
Set gateway.host: "0.0.0.0" and configure an auth token |
| Brave not being used | Missing "provider": "brave" field |
Add the provider field to tools.web.search |
The mixed provider/model key error is worth repeating: if you copy a GLM model name but your only configured key is MiniMax, nanobot will try to use the MiniMax key against Zhipu’s API and fail with a confusing error. Pin your providers.
Updating nanobot safely
Upgrade through whichever method you used to install:
# uv
uv tool upgrade nanobot-ai
# pip
pip install -U nanobot-ai
# From source
cd nanobot && git pull && python -m pip install -e .Back up before upgrading
Always back up ~/.nanobot/ before upgrading. Config, workspace memory, and session history live there. Stop the gateway first, then copy:
nanobot gateway stop
cp -r ~/.nanobot ~/.nanobot.bak
# Now upgrade
uv tool upgrade nanobot-aiv0.4.0 migrates session history to SQLite (it imports existing conversations and keeps source backups). In-app updates from the WebUI are gated on verified release approval.
To roll back: restore the backup, reinstall the previous version (uv tool install nanobot-ai==0.3.5 or whatever you were on).
VPS hosting for nanobot
A 2 vCPU / 4 GB VPS handles nanobot without breaking a sweat. It’s a light Python workload. I run mine on a Hetzner Cloud instance in the CX range. For current pricing and plan comparisons, see Hetzner’s cost-optimized CX23/CPX plans. Before committing to any provider, how to benchmark a cloud server before you commit is worth a read.
VPS discounts
Get €20 credit with Hetzner or try Hostinger VPS when you sign up through our referral links. The Hetzner credit covers a couple months of a small instance.
VPS prices moved across the board in 2026 - if you’re rethinking a rented box, see what changed and when a mini PC wins.
Quick setup on a fresh Ubuntu 24.04 VPS:
ssh root@YOUR_SERVER_IP
# Update system
apt update && apt upgrade -y
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
# Install nanobot
uv tool install nanobot-ai
nanobot --version
# Terminal setup wizard
nanobot onboard --wizard
# Verify model connectivity
nanobot -m "Hello!"
# Install as a persistent systemd user service
nanobot gateway install-service --manager systemd
loginctl enable-linger $USER
# Watch logs
journalctl --user -u nanobot-gateway -fIf you want to run local models alongside nanobot, check our guide on installing Ollama with Docker. nanobot’s built-in ollama and vllm providers work with any OpenAI-compatible endpoint.
If you’d rather skip the VPS entirely, Render has a one-click deploy blueprint (needs a paid plan with a persistent disk; set ANTHROPIC_API_KEY and NANOBOT_WEB_TOKEN).
nanobot vs OpenClaw
I run both, so here’s where things stand:
| Aspect | nanobot | OpenClaw |
|---|---|---|
| Install method | Script, uv, pip, Docker Compose | Custom installer script |
| Setup time | ~5 minutes | ~20 minutes |
| Admin surface | WebUI, TUI, SDK, OpenAI-compatible API | CLI + community dashboards |
| Channel support | 10+ (Discord, Telegram, Slack, WhatsApp, WeChat, Email, Teams, Signal, Matrix, and more) | 6 (Slack, Telegram, Discord, WhatsApp, iMessage, CLI) |
| Memory system | File-based (MEMORY.md, USER.md) + Dream consolidation + SQLite history | File-based + semantic search |
| Provider support | ~40 built-in | Several with OAuth options |
| Model presets | Yes, with fallback chains | No equivalent |
| MCP support | Yes (stdio + HTTP, WebUI catalog) | Limited |
| Automations | WebUI Tasks/Calendar, /goal, triggers |
Cron-style |
| Voice transcription | Built in (Groq default) | Via plugins |
| Resource usage | Light (Python) | Heavier (Node.js) |
OpenClaw has a polished setup wizard and the OAuth flow for existing Claude/ChatGPT subscriptions is nice. nanobot installs faster, supports more providers and channels, and has the WebUI for admin tasks. For OpenClaw details, see the full setup guide. If you want container-level isolation with Claude’s Agent SDK, see the NanoClaw deploy guide. For a Go binary on cheaper hardware, see the PicoClaw setup guide. For the smallest possible footprint (678 KB Zig binary), see the NullClaw deploy guide.
For other alternatives, check the OpenClaw alternatives roundup. To build something custom with multi-agent teams, look at the AI agent Discord bot guide using Agno.
How much does it cost to run nanobot?
VPS: around $5-10/month (Hetzner CX range or Hostinger). API: GLM-5.3-Flash or MiniMax M3.1-Flash at $0.15/M input tokens. For personal use, expect $5-15/month total. If you chat heavily or run automations, the Z.AI GLM Coding Plan from $18/month or MiniMax’s M Plan may be cheaper than pay-as-you-go. See our year-one Hetzner Cloud review for the VPS side.
Can I use nanobot without any API costs?
Yes. Configure the built-in ollama or vllm provider and point it at a local model server. You’ll need hardware that can run inference - see the best mini PC for local LLMs and Ollama for that. GLM-4.7-Flash is also free through Zhipu’s API if you just want a zero-cost cloud option. DuckDuckGo web search is free with no key.
Does nanobot work on a Raspberry Pi?
It runs fine with a remote API provider (MiniMax, Zhipu). A Pi 4 with 4 GB RAM handles the gateway without issues since the model inference happens in the cloud. Running local models on a Pi is a different story - don’t bother.
Can multiple people use one nanobot instance?
Yes. Add multiple user IDs to allowFrom in your channel config. Each person gets their own conversation context. Use allowChannels to restrict which channels the bot responds in, and groupPolicy: "mention" so it only reacts when @mentioned in group chats.
What's the difference between the agent, gateway, and webui commands?
nanobot opens the native TUI. nanobot agent is CLI chat (the -m flag sends a one-shot message). nanobot gateway starts the background service that connects to Discord, Telegram, and other chat channels. nanobot webui opens the browser admin panel on port 8765. For 24/7 use, you want the gateway as a systemd service.
Can I add Telegram alongside Discord?
Absolutely. Configure both channels in the same config.json and the gateway handles them simultaneously. See the OpenClaw setup guide for Telegram bot creation steps - the BotFather flow is identical.
What is `nanobot serve`?
It starts an OpenAI-compatible API on port 8900 with /v1/chat/completions, /v1/models, and /health endpoints. Point any OpenAI-compatible tool at your nanobot instance. Useful if you want other apps to use the same model pipeline.
Does nanobot support voice?
Yes. Voice transcription is built in, with Groq as the default provider. OpenAI, OpenRouter, Xiaomi MiMo, StepFun, AssemblyAI, and SiliconFlow are also supported.
If you want to explore other AI coding tools that pair well with self-hosted bots, our AI coding tools comparison compares the current options. For running agents with Python frameworks, check the Agno getting started guide.
Did this guide work for you?
Need help with Astro, VPS, or a self-hosted app? View services →


