Operations Runbook

Installation

From PyPI

pip install nanobot-ai

With uv

uv tool install nanobot-ai

With Matrix Support

pip install nanobot-ai[matrix]

First-Time Setup

# 1. Initialize config and workspace
nanobot onboard

# 2. Edit config to add API keys
# macOS/Linux:
vim ~/.nanobot/config.json
# Or use any editor

# 3. Verify setup
nanobot status

# 4. Test with a message
nanobot agent -m "Hello!"

Minimum Viable Config

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  }
}

Running

CLI Mode (Interactive)

nanobot agent              # Interactive REPL
nanobot agent -m "Hello"   # Single message
nanobot agent --no-markdown # Plain text output
nanobot agent --logs       # Show debug logs

Gateway Mode (Daemon)

nanobot gateway            # Foreground

Docker

# Build
docker build -t nanobot .

# First-time setup
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# Run gateway
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

# Single command
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"

Docker Compose

docker compose run --rm nanobot-cli onboard   # First-time setup
docker compose up -d nanobot-gateway           # Start gateway
docker compose logs -f nanobot-gateway         # View logs
docker compose down                            # Stop

systemd User Service (Linux)

Create ~/.config/systemd/user/nanobot-gateway.service:

[Unit]
Description=Nanobot Gateway
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/nanobot gateway
Restart=always
RestartSec=10
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=%h

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now nanobot-gateway
loginctl enable-linger $USER   # Keep running after logout

Common Operations

Check Status

nanobot status

Shows: configured providers, enabled channels, workspace path, model selection.

Reset a Session

Delete the session file:

rm ~/.nanobot/workspace/sessions/telegram_12345.jsonl

Or clear all sessions:

rm ~/.nanobot/workspace/sessions/*.jsonl

View Memory

cat ~/.nanobot/workspace/memory/MEMORY.md    # Long-term facts
cat ~/.nanobot/workspace/memory/HISTORY.md   # Chronological log

Edit Heartbeat Tasks

vim ~/.nanobot/workspace/HEARTBEAT.md

Format:

## Periodic Tasks
- [ ] Check weather forecast and send a summary
- [ ] Scan inbox for urgent emails

Add/Update Provider Credentials

Edit ~/.nanobot/config.json and restart:

vim ~/.nanobot/config.json
# If running as systemd service:
systemctl --user restart nanobot-gateway

OAuth Provider Login

nanobot provider login openai-codex
nanobot provider login github-copilot

WhatsApp QR Code Setup

# Terminal 1: start WhatsApp bridge
nanobot channels login

# Terminal 2: start gateway
nanobot gateway

Troubleshooting

Problem: “No provider configured”

Symptoms: nanobot agent returns an error about no API key.

Solution:

  1. Run nanobot status to check provider configuration

  2. Ensure at least one provider has a valid apiKey in ~/.nanobot/config.json

  3. Check the model name matches a configured provider

Problem: “Access denied for sender”

Symptoms: Bot ignores messages from a chat platform.

Solution:

  1. Check the allowFrom list in the channel config

  2. Add the sender’s ID to allowFrom

  3. Use ["*"] to allow all senders (for testing only)

  4. Check the logs for the actual sender ID being rejected

Problem: Channel fails to connect

Symptoms: “Channel not available” in logs.

Solution:

  1. Check that the channel SDK is installed (some are optional)

  2. Verify credentials (bot token, app secret, etc.)

  3. Check network connectivity and proxy settings

  4. For WebSocket channels (Feishu, DingTalk, Slack): ensure firewall allows outbound WebSocket

Problem: Tool execution failures

Symptoms: Agent reports tool errors.

Solution:

  1. If workspace-restricted (restrictToWorkspace: true), ensure the file/command is within ~/.nanobot/workspace/

  2. For shell commands: check tools.exec.timeout (default: 60s)

  3. For MCP tools: check toolTimeout on the MCP server config (default: 30s)

  4. Check file permissions

Problem: Memory/session corruption

Symptoms: Garbled responses, repeated context, or “tool_call_id not found” errors.

Solution:

  1. Delete the affected session file: rm ~/.nanobot/workspace/sessions/{key}.jsonl

  2. Memory files can be manually edited: ~/.nanobot/workspace/memory/MEMORY.md

  3. Restart the gateway

Problem: High memory usage

Symptoms: Python process consuming excessive RAM.

Solution:

  1. Lower agents.defaults.memory_window (default: 100) to consolidate more aggressively

  2. Delete old session files

  3. Reduce agents.defaults.max_tool_iterations (default: 40)

Configuration Reference

Environment Variables

The config supports environment variable overrides with prefix NANOBOT_ and nested delimiter __:

export NANOBOT_AGENTS__DEFAULTS__MODEL="openai/gpt-4o"
export NANOBOT_PROVIDERS__OPENAI__API_KEY="sk-xxx"

Key Configuration Paths

Setting

Path in JSON

Default

Description

Model

agents.defaults.model

anthropic/claude-opus-4-5

LLM model identifier

Provider

agents.defaults.provider

auto

Provider name or auto

Max tokens

agents.defaults.maxTokens

8192

Max response tokens

Temperature

agents.defaults.temperature

0.1

Sampling temperature

Workspace

agents.defaults.workspace

~/.nanobot/workspace

Working directory

Memory window

agents.defaults.memoryWindow

100

Messages before consolidation

Tool iterations

agents.defaults.maxToolIterations

40

Max tool call rounds

Workspace sandbox

tools.restrictToWorkspace

false

Sandbox all tools

Shell timeout

tools.exec.timeout

60

Shell command timeout (seconds)

Heartbeat interval

gateway.heartbeat.intervalS

1800

Heartbeat wake-up interval (seconds)

Progress streaming

channels.sendProgress

true

Stream partial responses

Monitoring

Log Output

  • CLI mode: logs to stderr (visible with --logs flag)

  • Gateway mode: logs to stderr (pipe to file or use journalctl for systemd)

  • Docker: docker compose logs -f nanobot-gateway

  • systemd: journalctl --user -u nanobot-gateway -f

Health Indicators

  • Gateway process is running

  • Channels show “enabled” in nanobot status

  • Heartbeat fires every 30 minutes (visible in logs)

  • Session files are being updated (check timestamps)

Backup & Recovery

What to Back Up

Path

Priority

Content

~/.nanobot/config.json

Critical

All credentials and settings

~/.nanobot/workspace/memory/

High

Long-term memory and history

~/.nanobot/workspace/sessions/

Medium

Conversation history

~/.nanobot/workspace/skills/

Medium

Custom user skills

~/.nanobot/workspace/HEARTBEAT.md

Low

Periodic task definitions

Recovery

  1. Reinstall nanobot

  2. Restore ~/.nanobot/config.json

  3. Restore ~/.nanobot/workspace/ directory

  4. Run nanobot status to verify