Quick Start

Overview

This guide walks you through setting up nanobot from scratch to having your first conversation. We’ll use OpenRouter as the LLM provider (recommended for global users) and configure optional web search capabilities.

Time to complete: ~2 minutesPrerequisites:

Python ≥3.11 installed
nanobot installed (see Installation)

Step-by-Step Setup

Initialize nanobot

Run the onboarding command to create configuration files and workspace:

nanobot onboard

This creates:

~/.nanobot/config.json - Main configuration file
~/.nanobot/workspace/ - Working directory for agent files
~/.nanobot/workspace/MEMORY.md - Persistent memory across conversations
~/.nanobot/workspace/HEARTBEAT.md - Periodic task definitions

You should see:

✓ Created config at /home/user/.nanobot/config.json
✓ Created workspace at /home/user/.nanobot/workspace

🐈 nanobot is ready!

Next steps:
  1. Add your API key to ~/.nanobot/config.json
     Get one at: https://openrouter.ai/keys
  2. Chat: nanobot agent -m "Hello!"

Get API keys

nanobot needs an LLM provider to function. We recommend OpenRouter for global access to all major models:

OpenRouter (Recommended)
Anthropic (Claude Direct)
OpenAI (GPT Direct)
Other Providers

Why OpenRouter?

Access to all major models (Claude, GPT-4, Gemini, etc.)
Pay-as-you-go pricing
No separate API keys needed for each provider

Get your API key:

Visit openrouter.ai/keys
Sign up or log in
Create a new API key
Copy the key (starts with sk-or-v1-)

For Claude direct access:

Visit console.anthropic.com
Create an account
Go to API Keys section
Generate a new key
Copy the key (starts with sk-ant-)

Direct Anthropic access gives you the latest Claude models but requires a separate API key.

For GPT direct access:

Visit platform.openai.com
Create an account
Go to API Keys section
Generate a new secret key
Copy the key (starts with sk-)

Optional: Get Brave Search API key (for web search)

Visit brave.com/search/api
Sign up for free tier (2,000 queries/month)
Copy your API key

Configure your API keys

Open the config file in your editor:

# Linux/macOS
nano ~/.nanobot/config.json
# or
vim ~/.nanobot/config.json

# Windows
notepad %USERPROFILE%\.nanobot\config.json

Add your API keys by merging these sections into the existing config:

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  },
  "tools": {
    "web": {
      "search": {
        "apiKey": "your-brave-api-key-here"
      }
    }
  }
}

Important: Only merge the sections shown above into your existing config. Don’t replace the entire file, as it contains other important settings.

The tools.web.search.apiKey field is optional. Web search will only work if you provide a Brave Search API key. All other features work without it.

Start chatting!

You’re all set! Start your first conversation:

nanobot agent -m "Hello! What can you help me with?"

Single message mode sends one message and exits:

$ nanobot agent -m "What's 2+2?"
⠋ nanobot is thinking...

🐈 nanobot
2 + 2 = 4

Interactive mode starts a persistent conversation:

$ nanobot agent
🐈 Interactive mode (type exit or Ctrl+C to quit)

You: Hello!
⠋ nanobot is thinking...

🐈 nanobot
Hello! I'm nanobot, your personal AI assistant. I can help you with:
- File operations and code editing
- Web search and research
- Task scheduling and reminders
- Running shell commands
- And much more!

What would you like to work on today?

You: _

To exit interactive mode, type exit, quit, or press Ctrl+C.

Common First Tasks

Now that nanobot is running, try these common tasks to explore its capabilities:

File Operations

nanobot agent -m "Create a file called test.txt with 'Hello World'"

nanobot can read, write, edit, and search files in your workspace.

Web Search

nanobot agent -m "Search for the latest AI news"

Requires Brave Search API key configured in Step 3.

Code Generation

nanobot agent -m "Write a Python function to calculate fibonacci numbers"

Generate, review, and save code directly to files.

Shell Commands

nanobot agent -m "List all Python files in the current directory"

Execute shell commands safely within workspace boundaries.

Example: Multi-Step Task

Try a complex task that demonstrates nanobot’s multi-step reasoning:

nanobot agent -m "Create a simple FastAPI server with a health check endpoint, save it to server.py, and show me how to run it"

The agent will:

Generate the FastAPI code
Save it to server.py in your workspace
Provide instructions to run the server

Example: Scheduled Tasks

Set up a recurring reminder:

nanobot agent -m "Remind me every day at 9 AM to review my tasks"

The agent will:

Create a cron job for the reminder
Store it in the cron service
Execute it daily at 9 AM (requires gateway running)

Scheduled tasks require the gateway to be running. See Running 24/7 section below.

Configuration Examples

Here are complete configuration examples for common setups:

Minimal Setup (OpenRouter Only)

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter",
      "temperature": 0.1,
      "maxTokens": 4096,
      "maxToolIterations": 40
    }
  }
}

With Web Search (OpenRouter + Brave)

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  },
  "tools": {
    "web": {
      "search": {
        "apiKey": "your-brave-api-key-here"
      }
    }
  }
}

Multi-Provider Setup

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    },
    "anthropic": {
      "apiKey": "sk-ant-your-key-here"
    },
    "openai": {
      "apiKey": "sk-your-openai-key-here"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter"
    }
  },
  "tools": {
    "web": {
      "search": {
        "apiKey": "your-brave-api-key-here"
      }
    }
  }
}

You can switch models on-the-fly by changing the model field or using different model names in the CLI.

Workspace Sandboxing (Production)

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5",
      "provider": "openrouter",
      "workspace": "/home/user/.nanobot/workspace"
    }
  },
  "tools": {
    "restrictToWorkspace": true,
    "exec": {
      "pathAppend": ""
    }
  }
}

restrictToWorkspace: true prevents the agent from accessing files outside the workspace directory. Recommended for production deployments.

Running 24/7

To enable scheduled tasks, heartbeat monitoring, and chat channel integrations, run the gateway:

nanobot gateway

The gateway:

✅ Keeps the agent running continuously
✅ Processes messages from Telegram, Discord, etc.
✅ Executes scheduled cron jobs
✅ Runs periodic heartbeat tasks every 30 minutes

Gateway output:

🐈 Starting nanobot gateway on port 18790...
✓ Channels enabled: telegram
✓ Cron: 3 scheduled jobs
✓ Heartbeat: every 1800s

Run the gateway in the background or as a system service for 24/7 operation. See Linux Service Setup below.

Linux Service Setup

To run the gateway as a systemd service that starts automatically:

Find nanobot path

which nanobot
# Example output: /home/user/.local/bin/nanobot

Create service file

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

Enable and start

systemctl --user daemon-reload
systemctl --user enable --now nanobot-gateway

Enable lingering to keep it running after logout:

loginctl enable-linger $USER

Manage service

# Check status
systemctl --user status nanobot-gateway

# View logs
journalctl --user -u nanobot-gateway -f

# Restart after config changes
systemctl --user restart nanobot-gateway

# Stop service
systemctl --user stop nanobot-gateway

Troubleshooting

Error: No API key configured

Problem: You see this error when running nanobot agent:

Error: No API key configured.
Set one in ~/.nanobot/config.json under providers section

Solution: Make sure you’ve added your API key to the config file:

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

Verify with:

cat ~/.nanobot/config.json | grep apiKey

Model not responding / Timeout

Problem: The agent hangs or times out when processing requests.Possible causes:

Invalid API key: Check that your key is correct
Network issues: Test connectivity to the provider
Model unavailable: Try a different model

Solutions:Check provider status:

nanobot status

Test with a different model:

{
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4"
    }
  }
}

Enable debug logs:

nanobot agent --logs -m "Hello"

Web search not working

Problem: Agent says “web search not available” or searches fail.Solution: Add Brave Search API key to config:

{
  "tools": {
    "web": {
      "search": {
        "apiKey": "your-brave-api-key-here"
      }
    }
  }
}

Get a free API key at brave.com/search/api.

Can't access files outside workspace

Problem: Agent can’t read/write files in other directories.Cause: restrictToWorkspace: true in config (security feature).Solutions:Option 1: Work within the workspace

cd ~/.nanobot/workspace
nanobot agent -m "Create a file test.txt"

Option 2: Disable restriction (not recommended for production)

{
  "tools": {
    "restrictToWorkspace": false
  }
}

Option 3: Change workspace directory

{
  "agents": {
    "defaults": {
      "workspace": "/path/to/your/project"
    }
  }
}

Interactive mode exits immediately

Problem: nanobot agent starts but exits right away.Possible causes:

Ctrl+D pressed: EOF signal exits the session
Piped input: Interactive mode requires a TTY

Solution: Run directly in terminal (not through pipes)

nanobot agent

For non-interactive usage, use single-message mode:

nanobot agent -m "Your message here"

Next Steps

Now that you have nanobot running, explore more features:

Connect Chat Channels

Set up Telegram, Discord, WhatsApp, and more

Configure Providers

Add more LLM providers and switch between models

Explore Tools

Learn about built-in tools and MCP integration

Advanced Configuration

Fine-tune temperature, tokens, memory, and more

GitHub Repository

Star the repo and check out the source code

Community Support

Join the Discord server for help and discussions

Pro tip: nanobot’s configuration is hot-reloadable. For the gateway, restart it after config changes with systemctl --user restart nanobot-gateway. For CLI mode, changes take effect on next run.

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

Overview

Step-by-Step Setup

Common First Tasks

File Operations

Web Search

Code Generation

Shell Commands

Example: Multi-Step Task

Example: Scheduled Tasks

Configuration Examples

Running 24/7

Linux Service Setup

Troubleshooting

Next Steps

Connect Chat Channels

Configure Providers

Explore Tools

Advanced Configuration

GitHub Repository

Community Support

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

​Overview

​Step-by-Step Setup

​Common First Tasks

File Operations

Web Search

Code Generation

Shell Commands

​Example: Multi-Step Task

​Example: Scheduled Tasks

​Configuration Examples

​Running 24/7

​Linux Service Setup

​Troubleshooting

​Next Steps

Connect Chat Channels

Configure Providers

Explore Tools

Advanced Configuration

GitHub Repository

Community Support

Build docs developers (and LLMs) love

Overview

Step-by-Step Setup

Common First Tasks

Example: Multi-Step Task

Example: Scheduled Tasks

Configuration Examples

Running 24/7

Linux Service Setup

Troubleshooting

Next Steps