This guide provides an Ansible playbook to deploy Nanobot natively (without Docker) on Debian 10+, Ubuntu 20.04+, and RHEL 9+ compatible hosts using pip or uv package installation. Nanobot is an ultra-lightweight Python AI agent with ~4,000 lines of code supporting 10+ messaging platforms.
Important: Nanobot uses file-based configuration stored in ~/.nanobot/config.json. No external database is required.
Official Resources:
---
- name: Deploy Nanobot (Native pip Installation)
hosts: nanobot
become: true
vars:
# Application settings
nanobot_user: nanobot
nanobot_home: /home/nanobot
nanobot_version: "latest"
# Gateway settings
gateway_port: 18790
gateway_host: "0.0.0.0"
# Provider settings
openrouter_api_key: "{{ vault_nanobot_openrouter_api_key }}"
telegram_bot_token: "{{ vault_nanobot_telegram_token | default('') }}"
allowed_user_ids: []
tasks:
- name: Install Python and prerequisites (Debian/Ubuntu)
apt:
name:
- python3
- python3-pip
- python3-venv
- curl
- ca-certificates
state: present
update_cache: true
when: ansible_os_family == "Debian"
- name: Install Python and prerequisites (RHEL)
dnf:
name:
- python3
- python3-pip
- curl
- ca-certificates
state: present
when: ansible_os_family == "RedHat"
- name: Install uv (fast Python package manager)
become: false
shell: |
curl -LsSf https://astral.sh/uv/install.sh | sh
args:
creates: "{{ ansible_user_dir }}/.local/bin/uv"
- name: Add uv to PATH
become: false
lineinfile:
path: "{{ ansible_user_dir }}/.bashrc"
line: 'export PATH="$HOME/.local/bin:$PATH"'
create: true
- name: Create Nanobot system user
user:
name: "{{ nanobot_user }}"
home: "{{ nanobot_home }}"
shell: /bin/bash
system: true
create_home: true
comment: "Nanobot AI Agent Service"
- name: Install Nanobot via uv (recommended)
become: true
become_user: "{{ nanobot_user }}"
shell: |
uv tool install nanobot-ai
environment:
PATH: "{{ ansible_user_dir }}/.local/bin:{{ ansible_env.PATH }}"
register: uv_install
changed_when: "'Successfully installed' in uv_install.stdout"
- name: Install Nanobot via pip (fallback)
become: true
become_user: "{{ nanobot_user }}"
pip:
name: nanobot-ai
state: present
when: uv_install is failed
- name: Create .nanobot directory
file:
path: "{{ nanobot_home }}/.nanobot"
state: directory
mode: "0700"
owner: "{{ nanobot_user }}"
group: "{{ nanobot_user }}"
- name: Create workspace directory
file:
path: "{{ nanobot_home }}/.nanobot/workspace"
state: directory
mode: "0700"
owner: "{{ nanobot_user }}"
group: "{{ nanobot_user }}"
- name: Write Nanobot configuration file
copy:
dest: "{{ nanobot_home }}/.nanobot/config.json"
mode: "0600"
owner: "{{ nanobot_user }}"
group: "{{ nanobot_user }}"
content: |
{
"providers": {
"openrouter": {
"apiKey": "{{ openrouter_api_key }}"
}
},
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-5",
"provider": "openrouter"
}
},
"channels": {
{% if telegram_bot_token and telegram_bot_token != '' %}
"telegram": {
"enabled": true,
"token": "{{ telegram_bot_token }}",
"allowFrom": {{ allowed_user_ids | to_json }}
}
{% else %}
"telegram": {
"enabled": false
}
{% endif %}
}
}
- name: Create systemd service file
copy:
dest: /etc/systemd/system/nanobot.service
mode: "0644"
content: |
[Unit]
Description=Nanobot AI Agent Gateway
After=network.target
Documentation=https://github.com/HKUDS/nanobot
[Service]
Type=simple
User={{ nanobot_user }}
Group={{ nanobot_user }}
WorkingDirectory={{ nanobot_home }}
Environment=HOME={{ nanobot_home }}
Environment=PATH={{ ansible_user_dir }}/.local/bin:/usr/local/bin:/usr/bin:/bin
ExecStart={{ ansible_user_dir }}/.local/bin/nanobot gateway --port {{ gateway_port }}
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
# Security hardening
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths={{ nanobot_home }}/.nanobot
[Install]
WantedBy=multi-user.target
- name: Reload systemd daemon
systemd:
daemon_reload: true
- name: Enable Nanobot service
systemd:
name: nanobot
enabled: true
daemon_reload: true
- name: Start Nanobot service
systemd:
name: nanobot
state: started
- name: Wait for Nanobot to be ready
wait_for:
port: "{{ gateway_port }}"
host: "{{ gateway_host }}"
timeout: 30
ignore_errors: true
- name: Display deployment information
debug:
msg: |
Nanobot deployment complete!
Service Status: Active
Gateway Port: {{ gateway_port }}
Gateway Host: {{ gateway_host }}
Installation Method: {{ 'uv' if uv_install is succeeded else 'pip' }}
IMPORTANT:
- Nanobot binds to {{ gateway_host }}:{{ gateway_port }}
- Store API keys securely in ~/.nanobot/config.json
- Run 'nanobot status' for health checks
- See 'nanobot onboard' for guided setup
Save the playbook as deploy-nanobot-native.yml.
Create an inventory file (inventory.ini):
[nanobot]
server1.example.com
server2.example.com
[nanobot:vars]
ansible_user=deploy
ansible_ssh_private_key_file=~/.ssh/id_ed25519
Use Ansible Vault to store sensitive values:
# Create vault file
ansible-vault create group_vars/nanobot/vault.yml
Add your API keys:
vault_nanobot_openrouter_api_key: "sk-or-v1-your-actual-api-key"
vault_nanobot_telegram_token: "YOUR_TELEGRAM_BOT_TOKEN"
# Basic run
ansible-playbook -i inventory.ini deploy-nanobot-native.yml
# With vault
ansible-playbook -i inventory.ini deploy-nanobot-native.yml --ask-vault-pass
uv (fast Python package manager) with pip fallback~/.nanobot/config.json| Variable | Default | Description |
|---|---|---|
nanobot_user |
nanobot |
System user for Nanobot |
nanobot_home |
/home/nanobot |
Home directory |
nanobot_version |
latest |
PyPI version to install |
gateway_port |
18790 |
Gateway port |
gateway_host |
0.0.0.0 |
Gateway bind address |
openrouter_api_key |
- |
OpenRouter API key (use Ansible Vault) |
telegram_bot_token |
- |
Telegram bot token (use Ansible Vault) |
allowed_user_ids |
[] |
List of allowed Telegram user IDs |
| Provider | Config Key | Notes |
|---|---|---|
| OpenRouter | openrouter |
Multi-provider aggregator (recommended) |
| Anthropic | anthropic |
Claude models |
| OpenAI | openai |
GPT-4, GPT-3.5-turbo |
| DeepSeek | deepseek |
DeepSeek models |
| Groq | groq |
Fast inference |
| Google Gemini | gemini |
Google AI models |
| Zhipu | zhipu |
Chinese LLM provider |
| MiniMax | minimax |
MiniMax models |
| SiliconFlow | siliconflow |
Chinese LLM provider |
| VolcEngine | volcengine |
ByteDance AI platform |
| DashScope | dashscope |
Alibaba AI platform |
| MoonShot | moonshot |
MoonShot AI |
| Platform | Config Key | Notes |
|---|---|---|
| Telegram | telegram |
Bot token from @BotFather |
| Discord | discord |
Bot token, requires Message Content intent |
whatsapp |
QR scan, requires Node.js 18+ | |
| Slack | slack |
Bot token + App token (Socket Mode) |
| Feishu | feishu |
App ID + App Secret |
| DingTalk | dingtalk |
App Key + App Secret |
qq |
Bot credentials | |
email |
IMAP/SMTP configuration | |
| Matrix | matrix |
Homeserver + access token, E2EE support |
| Mochat | mochat |
Enterprise messaging |
| Wecom | wecom |
Bot ID + Bot Secret (Enterprise WeChat) |
# Check systemd status
systemctl status nanobot
# View logs
journalctl -u nanobot -f
# Test the installation
nanobot --version
nanobot status
By default, Nanobot gateway binds to port 18790:
# SSH to server and test
ssh user@server
curl http://127.0.0.1:18790
Edit the configuration file:
# SSH to server
ssh user@server
# Switch to nanobot user
sudo su - nanobot
# Edit config
nano ~/.nanobot/config.json
# Restart service
sudo systemctl restart nanobot
For interactive setup:
sudo su - nanobot
nanobot onboard
systemctl status nanobot
# Full logs
journalctl -u nanobot -f
# Last 100 lines
journalctl -u nanobot -n 100
# Since boot
journalctl -u nanobot -b
systemctl restart nanobot
systemctl stop nanobot
# Update via uv
sudo su - nanobot
uv tool upgrade nanobot-ai
# Or via pip
pip install --upgrade nanobot-ai
# Restart service
sudo systemctl restart nanobot
systemctl status nanobot
journalctl -u nanobot -f
sudo su - nanobot
nanobot status
sudo su - nanobot
nanobot agent -m "Hello!"
sudo su - nanobot
nanobot gateway --port 18790
nanobot --version
nanobot --help
python3 --version # Should be 3.11 or 3.12
nanobot status regularly for health checksjournalctl -u nanobotFor detailed security guidance, see Nanobot Security.
We develop tailored automation solutions for:
Let’s discuss your requirements: office@linux-server-admin.com | Contact