Skip to content
Get packs

Guide · Open source

How to use nanobot: install, set up a model and run it

Updated · written with AI from the project's own documentation and checked against our catalogue data

nanobot is an open-source, self-hosted personal AI agent framework written in Python. You can use it in a browser, a terminal, or chat apps such as Telegram or Discord to work with files, remember preferences, and schedule tasks. This guide walks through installing it, what you need before starting, and where to go next. nanobot does not include a model, so you will also need access to a supported model provider or a local model server.

nanobotHKUDS/nanobot · ★ 49.8k · MIT

Quick start

  1. 1Check Python. Confirm you have Python 3.11 or newer installed.
  2. 2Get model access. Set up an account with a supported model provider or a local model server. nanobot does not include a model.
  3. 3Install the package. Run uv tool install nanobot-ai, or activate a virtual environment and run python -m pip install nanobot-ai.
  4. 4Open setup. Run nanobot webui for browser setup, or nanobot onboard --wizard for terminal setup.
  5. 5Connect a model. Enter the details for your model provider or local model server during setup, following the provider documentation.
  6. 6Try a first task. Ask nanobot a question in the WebUI or terminal, then try a file task such as summarizing a PDF or Word document.

What you need before you install nanobot

nanobot requires Python 3.11 or newer. You also need access to a supported model provider or a local model server, because nanobot does not supply the AI model itself. Model fees or local hardware requirements depend on the service you choose.

  • Python 3.11 or newer
  • Access to a supported model provider or a local model server
  • Optional: a chat app account such as Telegram, Discord, or Slack if you want to reach nanobot from chat

Install nanobot with uv or pip

The README lists two package-manager routes for the stable release. Use uv if you want an isolated command-line installation. Use pip if you already manage your own virtual environment.

If pip reports externally-managed-environment, the README suggests using the recommended installer, uv tool install nanobot-ai, or pipx install nanobot-ai instead.

  • uv: install the stable release as an isolated tool
  • pip: activate your virtual environment first, then install the stable package
  • The installer scripts for macOS, Linux and Windows are an alternative option described in the README
uv tool install nanobot-ai

Set up nanobot with pip in a virtual environment

If you use pip, activate your virtual environment before running the install command. This keeps nanobot separate from other Python packages on your system.

For the Python SDK, install nanobot-ai in your application's virtual environment so the application can import it. A separate uv tool environment does not make the SDK importable there.

python -m pip install nanobot-ai

Start nanobot and complete setup

After installing with uv or pip, the README says to run nanobot webui for browser setup. If you prefer terminal-only setup, run nanobot onboard --wizard instead.

Setup is where you connect your model provider or local model server. The README points to the provider documentation for supported options.

  • Browser setup: nanobot webui
  • Terminal-only setup: nanobot onboard --wizard
nanobot webui

Use nanobot in the browser, terminal or chat apps

nanobot can run in a browser WebUI or in a terminal. It can also connect to chat channels including Telegram, Discord, Slack, WeChat, Email, Mattermost and Linear. The README links a chat app guide for channel setup.

The README also mentions that nanobot can read PDF, Word, Excel and PowerPoint files with built-in file tools, for example to summarize a report.

  • Browser WebUI for everyday chat
  • Terminal for command-line use
  • Chat apps such as Telegram, Discord and Slack via the chat app guide
  • File tasks such as summarizing PDF, .docx, .xlsx or .pptx files

Understand memory, automation and extensions

nanobot keeps session history and long-term memory, and it can run scheduled automations and longer goals. It also supports MCP integrations, shell and web tools, and multi-agent delegation according to the README.

Developers can use the Python SDK or an OpenAI-compatible API to integrate nanobot into other software. The README links the architecture and provider extension docs for people who want to change the internals.

  • Session history and long-term memory
  • Scheduled automations and long-running goals
  • MCP integrations, shell, web search and fetch tools
  • Python SDK and OpenAI-compatible API
  • Deployment as a long-running gateway

What people use it for

  • Summarize PDF, Word, Excel or PowerPoint reports with an AI assistant
  • Reach a personal assistant from Telegram, Discord or Slack
  • Keep preferences and long-term memory across conversations
  • Schedule recurring tasks with nanobot automations
  • Build a small Python agent with memory, tools and MCP support

Frequently asked questions

Is nanobot free?

The README states that nanobot is MIT licensed and open source. It does not supply a model account, so model fees or local hardware costs depend on the provider or local server you choose.

What do I need to run nanobot?

You need Python 3.11 or newer and access to a supported model provider or a local model server. nanobot is self-hosted, so you run it on your own machine or server.

How do I install nanobot?

Run uv tool install nanobot-ai with uv, or run python -m pip install nanobot-ai inside an activated virtual environment with pip. The README also describes installer scripts for macOS, Linux and Windows.

Can I use nanobot without a terminal?

The README links a separate guide, Start Without Technical Background, for people who are not comfortable with terminals or configuration. The project's own description says the non-technical guide is the route for those users.

What is the difference between nanobot and Open Interpreter or Open WebUI?

The source does not compare nanobot with these projects in detail. The README describes nanobot as a self-hosted personal agent framework with a WebUI, tools, memory, MCP and chat app access, which you can inspect and customize.

Why does nanobot say no model is included?

nanobot is a framework that connects to a model. You must supply a model through a supported provider or a local model server, and the README says nanobot does not supply a model account.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

nanobot suits people and developers who want a self-hosted, inspectable personal assistant with memory, tools, MCP and chat app access, and who can supply their own model. It is a poor fit if you want a ready-made hosted service with no setup, or if you need a documented enterprise security model, which the README does not describe in detail.

Install options & downloads