Bitdoze logo

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.

Dragos

Updated Published 35 min read

Nanobot AI assistant running on a VPS, configured with GLM-5.3 and MiniMax M3.1 Flash providers

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 GitHub

What 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:

text
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:

bash
curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | bash

On Windows, use install.ps1 instead. After installation, verify:

bash
nanobot --version

uv or pip

If you prefer managing Python packages yourself:

bash
# With uv (recommended - faster, isolated)
uv tool install nanobot-ai

# Or with pip
pip install nanobot-ai

If you don’t have uv yet, see getting started with uv. Verify:

bash
nanobot --version

From 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):

bash
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
python -m pip install -e .

Verify:

bash
nanobot --version

After installing, initialize the workspace and config:

bash
nanobot onboard

This 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:

bash
nanobot onboard --wizard

To refresh config non-interactively after editing config.json by hand:

bash
nanobot onboard --refresh

Verify everything is wired up:

bash
nanobot status

This 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:

bash
nanobot webui

This 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:

bash
ssh -N -L 127.0.0.1:8765:127.0.0.1:8765 user@YOUR_SERVER_IP

Then 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

  1. Go to platform.minimax.io (global) or minimaxi.com (mainland China)
  2. Create an account and generate an API key
  3. 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:

bash
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:

json
{
  "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:

json
{
  "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:

bash
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:

json
{
  "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

  1. Go to z.ai
  2. 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:

bash
export ZHIPU_API_KEY="your-zhipu-api-key"

Add GLM-5.3 to config

json
{
  "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:

json
{
  "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:

bash
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:

json
{
  "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:

json
{
  "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

  1. Go to brave.com/search/api
  2. Sign up for an account
  3. The free tier gives you up to $20 in prepaid credits per month (no subscription)
  4. Generate an API key from the dashboard

Enable Brave in config

json
{
  "tools": {
    "web": {
      "search": {
        "provider": "brave",
        "apiKey": "${BRAVE_API_KEY}",
        "maxResults": 5
      }
    }
  }
}

Export the key:

bash
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

  1. Go to discord.com/developers/applications
  2. Click New Application, give it a name
  3. Go to Bot in the left sidebar, click Add Bot
  4. Copy the bot token

Enable intents

Still in the Bot settings page:

  1. Scroll down to Privileged Gateway Intents
  2. Enable MESSAGE CONTENT INTENT (required, or the bot can’t read messages)
  3. Optionally enable SERVER MEMBERS INTENT if you plan to use allow lists

Get your user ID

  1. Open Discord Settings, go to Advanced, enable Developer Mode
  2. Right-click your avatar anywhere in Discord
  3. Click Copy User ID

Configure nanobot

json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}",
      "allowFrom": ["YOUR_USER_ID"],
      "allowChannels": [],
      "groupPolicy": "mention",
      "streaming": true,
      "replyToMessage": false
    }
  }
}

Export the bot token:

bash
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

  1. In the Discord developer portal, go to OAuth2 then URL Generator
  2. Under Scopes, check bot
  3. Under Bot Permissions, check Send Messages and Read Message History
  4. Copy the generated URL and open it in your browser
  5. Select the server you want to add the bot to

Start the gateway and verify

For a quick test:

bash
nanobot gateway

Send 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:

json
{
  "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:

bash
nano ~/.nanobot/workspace/USER.md

Add 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

json
{
  "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

bash
git clone https://github.com/HKUDS/nanobot.git && cd nanobot
docker compose up -d
docker compose logs

First 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:

bash
curl --fail http://127.0.0.1:18790/health

The 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:

bash
# 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 gateway

Build 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:

bash
nanobot gateway install-service --manager systemd

This creates ~/.config/systemd/user/nanobot-gateway.service, enables it, and starts it. Preview without installing:

bash
nanobot gateway install-service --manager systemd --dry-run

Manage the service:

bash
systemctl --user status nanobot-gateway
systemctl --user restart nanobot-gateway
journalctl --user -u nanobot-gateway -f

To keep user services alive after you log out:

bash
loginctl enable-linger $USER

For 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:

bash
nanobot gateway --background
nanobot gateway stop
nanobot gateway restart

Automations: 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:

text
/trigger PR review

nanobot replies with a trigger ID and a ready-to-copy command:

bash
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

json
{
  "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:

json
{
  "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 install
  • nanobot status - validates provider/model config
  • nanobot -m “Hello!” - confirms LLM connectivity
  • curl –fail http://127.0.0.1:18790/health - gateway is up
  • Send a Discord DM and confirm a reply
  • journalctl –user -u nanobot-gateway -f or docker 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:

bash
# 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:

bash
nanobot gateway stop
cp -r ~/.nanobot ~/.nanobot.bak
# Now upgrade
uv tool upgrade nanobot-ai

v0.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:

bash
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 -f

If 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 →