How to Install and Run Nanobot AI Agent on Windows (Complete Setup Guide)

Nanobot is an open-source, ultra-lightweight AI agent built in the spirit of OpenClaw, Claude Code, and Codex. It keeps the core agent loop small and readable while supporting chat channels, memory, MCP, and practical deployment paths so you can go from a fresh install to a long-running personal AI agent with minimal overhead.

Why Nanobot?

• Ultra-lightweight – stable long-running agent behaviour with a small, readable core
• Research-ready – simple enough to study, modify, and extend
• Practical – chat channels, API, memory, MCP, and deployment paths already built in
• Hackable – start fast, go deeper through repo docs rather than a monolithic landing page

Prerequisites

Before you begin, make sure you have Python 3.12 installed on your Windows machine. Nanobot works best with 3.12 for day-to-day stability. You will also need a free API key from OpenRouter (covered in Step 4 below).

Step 1: Install Nanobot

Open PowerShell and run:

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

Using py -3.12 ensures you are installing into the correct Python version rather than whatever pip resolves to by default.

Step 2: Fix the PATH Warning (if it appears)

After installing, you may see this warning:

nanobot.exe is installed in '...\Scripts' which is not on PATH

This means Nanobot installed correctly, but Windows does not know where to find the nanobot command when you type it in the terminal.

Quick fix – use this command instead of nanobot for now:

py -3.12 -m nanobot

This bypasses the PATH issue entirely and works immediately.

Permanent fix (recommended):

1. Press the Windows key
2. Search: Environment Variables
3. Open → Edit the system environment variables
4. Click Environment Variables
5. Under User variables → find Path → click Edit
6. Click New and paste:

C:\Users\....\Local\Python\pythoncore-3.14-64\Scripts

7. Click OK → OK → OK
8. Close PowerShell and reopen it

After restarting the terminal, the plain nanobot command will work.

Step 3: First-Time Onboarding

Before running the agent for the first time, you must run the onboarding command. This creates your config file, sets up your workspace, and prompts you for API keys.

py -3.12 -m nanobot onboard

Run this once. You do not need to repeat it on future sessions.

Step 4: Get a Free API Key from OpenRouter

Nanobot connects to AI models through a provider. The easiest free option is OpenRouter.

1. Go to Openrouter unified interface.
2. Sign up. Google login works
3. Copy your API key

Step 5: Configure Nanobot

Open your config file at:

C:\Users\....\.nanobot\config.json

Update it with the following, replacing the placeholder with your real API key:

{
  "provider": "openrouter",
  "api_key": "PASTE_YOUR_KEY_HERE",
  "model": "mistralai/mistral-7b-instruct"
}

mistralai/mistral-7b-instruct is a free model available on OpenRouter and works well for general chat and agent tasks.

If your config file already has an openrouter block instead of the simpler format above, find and edit these three values directly:

Change the provider:

"provider": "openrouter"

Add your API key:

"openrouter": {
  "apiKey": "PASTE_YOUR_KEY_HERE",

Change the model:

"model": "openrouter/auto"

Save the file when done.

Step 6: Run the AI Agent

py -3.12 -m nanobot agent

You are now in a live chat session with your AI. Type:

hello

And Nanobot will respond. That’s the full setup complete.

Optional: Start the API Server

If you want to use Nanobot as a backend API rather than a terminal chat interface, run:

py -3.12 -m nanobot serve

Quick Reference: The Three Core Commands

Command	What it does
py -3.12 -m nanobot onboard	First-time setup .run once
py -3.12 -m nanobot agent	Start the AI chat agent
py -3.12 -m nanobot serve	Start the backend API server

Troubleshooting

1.nanobot command not found after install : Use py -3.12 -m nanobot as a temporary fix. For a permanent fix, add the Scripts folder to your PATH as described in Step 2, then restart your terminal.

2. Installed into the wrong Python version: If you have multiple Python versions on your machine, always use py -3.12 -m pip install -e . to install, and py -3.12 -m nanobot to run. This pins the commands to Python 3.12 explicitly.

3. API key errors or model not found: Double-check your config.json — the key must be inside quotes and the provider must be set to openrouter. Make sure there are no trailing commas or missing brackets in the JSON file.

4. Agent starts but does not respond: Confirm your OpenRouter account has credits or that you selected a free-tier model such as mistralai/mistral-7b-instruct. You can check available free models.

Nanobot Reflects a Growing Trend Toward Lightweight, Self-Hosted AI Agents

The rise of tools like Nanobot signals a clear shift in how developers approach AI. Instead of relying on heavy, complex frameworks or closed SaaS platforms, there is growing demand for lightweight, self-hosted AI agents that are easier to understand, modify, and run independently.

Nanobot fits directly into this trend. Its small and readable core makes it accessible for developers who want control over how their AI agent behaves, rather than working with black-box systems. This is especially important for experimentation, research, and building custom automation workflows.

At the same time, integrations with providers like OpenRouter show how modern AI agents are becoming more flexible. Developers can switch between models without changing the core system, making setups like Nanobot more adaptable compared to traditional approaches.

This shift is also connected to a broader move toward self-hosted infrastructure. Running AI agents on personal servers or VPS environments allows for better control, privacy, and long-term cost efficiency. As more developers build their own automation stacks, lightweight agents like Nanobot are becoming a practical starting point.

In simple terms, Nanobot is not just a tool it represents where AI development is heading; smaller, flexible, and fully in your control.

Conclusion

Nanobot proves that you don’t need a heavy, complex system to run a functional AI agent. With a lightweight core, OpenRouter integration, and simple setup, you can go from installation to a working AI assistant in minutes.

But running an AI agent locally is just the starting point. The real value comes when the agent runs continuously, handles tasks in the background, and integrates with real workflows. That requires a stable environment, consistent uptime, and enough resources to handle API calls and processing without interruption.

If you’re planning to move beyond testing and actually use Nanobot for automation, development support, or API-based services, running it on a reliable VPS is the next step. A KVM VPS hosting like Ucartz gives you the control and stability needed to keep your AI agent running 24/7 without depending on your local machine.

FAQ

1. What is Nanobot AI agent?
Nanobot is an open-source lightweight AI agent designed for easy customization, automation, and long-running tasks.

2. Do I need coding skills to use Nanobot?
Basic command-line and configuration knowledge is required to install and run Nanobot effectively.

3. Is Nanobot free to use?
Nanobot is open-source, but it requires an API key from providers like OpenRouter which may have usage limits.

4. Can Nanobot run continuously in the background?
Yes, Nanobot can run as a long-running agent using tools like PM2 or screen on a VPS.

5. Which AI models work with Nanobot?
Nanobot supports models via OpenRouter, including free options like Mistral 7B.

6. Can I use Nanobot with n8n automation?
Yes, Nanobot can be integrated with n8n via API to create AI-driven automation workflows.