Docker Compose is the recommended way to deploy Nanobot for production use. This guide covers Docker deployment with persistent configuration.
Nanobot does not have an official Docker Hub image. You build the image locally from the repository.
| Build Method | Image Name | Size |
|---|---|---|
| Local build | nanobot (from Dockerfile) |
~500 MB |
| Base image | ghcr.io/astral-sh/uv:python3.12-bookworm-slim |
- |
git clone https://github.com/HKUDS/nanobot
cd nanobot
# Run onboarding to create configuration
docker compose run --rm nanobot-cli onboard
# This creates ~/.nanobot/config.json
Edit ~/.nanobot/config.json:
{
"providers": {
"openrouter": {
"apiKey": "sk-or-v1-your-openrouter-key"
}
},
"agents": {
"defaults": {
"model": "anthropic/claude-opus-4-5",
"provider": "openrouter"
}
},
"channels": {
"telegram": {
"enabled": true,
"token": "YOUR_TELEGRAM_BOT_TOKEN",
"allowFrom": ["YOUR_USER_ID"]
}
}
}
# Start the gateway service
docker compose up -d nanobot-gateway
# Check status
docker compose ps
# View logs
docker compose logs -f nanobot-gateway
# Test CLI command
docker compose run --rm nanobot-cli agent -m "Hello!"
Access the gateway at http://localhost:18790.
The official docker-compose.yml:
x-common-config: &common-config
build:
context: .
dockerfile: Dockerfile
volumes:
- ~/.nanobot:/root/.nanobot
services:
nanobot-gateway:
container_name: nanobot-gateway
<<: *common-config
command: ["gateway"]
restart: unless-stopped
ports:
- "18790:18790"
deploy:
resources:
limits:
cpus: '1'
memory: 1G
reservations:
cpus: '0.25'
memory: 256M
nanobot-cli:
<<: *common-config
profiles:
- cli
command: ["status"]
stdin_open: true
tty: true
The official Dockerfile:
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
# Install Node.js 20 for the WhatsApp bridge
RUN apt-get update && \
apt-get install -y --no-install-recommends curl ca-certificates gnupg git && \
mkdir -p /etc/apt/keyrings && \
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \
apt-get update && \
apt-get install -y --no-install-recommends nodejs && \
apt-get purge -y gnupg && \
apt-get autoremove -y && \
rm -rf /var/lib/apt/lists/*
WORKDIR /app
# Install Python dependencies first (cached layer)
COPY pyproject.toml README.md LICENSE ./
RUN mkdir -p nanobot bridge && touch nanobot/__init__.py && \
uv pip install --system --no-cache . && \
rm -rf nanobot bridge
# Copy the full source and install
COPY nanobot/ nanobot/
COPY bridge/ bridge/
RUN uv pip install --system --no-cache .
# Build the WhatsApp bridge
WORKDIR /app/bridge
RUN npm install && npm run build
WORKDIR /app
# Create config directory
RUN mkdir -p /root/.nanobot
# Gateway default port
EXPOSE 18790
ENTRYPOINT ["nanobot"]
CMD ["status"]
docker build -t nanobot .
docker run -d \
--name nanobot-gateway \
-p 18790:18790 \
-v ~/.nanobot:/root/.nanobot \
nanobot gateway
# Check status
docker run --rm -v ~/.nanobot:/root/.nanobot nanobot status
# Run agent command
docker run --rm -v ~/.nanobot:/root/.nanobot nanobot agent -m "Hello!"
# Onboarding (first time)
docker run --rm -v ~/.nanobot:/root/.nanobot nanobot onboard
Configuration is persisted in:
~/.nanobot/ - Configuration directory
config.json - Main configuration fileworkspace/ - Agent workspace (scheduled tasks, etc.)# Pull latest changes
cd nanobot
git pull
# Rebuild image
docker compose build
# Restart services
docker compose down
docker compose up -d
docker compose ps
# All services
docker compose logs -f
# Gateway only
docker compose logs -f nanobot-gateway
# CLI output
docker compose run --rm nanobot-cli status
Gateway won’t start:
# Check configuration
cat ~/.nanobot/config.json
# Verify API keys are set
docker compose run --rm nanobot-cli status
WhatsApp channel issues:
# Verify Node.js is installed in container
docker compose exec nanobot-gateway node --version
# Should output: v20.x.x
Permission errors:
# Fix directory permissions
chmod -R 755 ~/.nanobot
For production environments:
~/.nanobot~/.nanobotserver {
listen 443 ssl http2;
server_name nanobot.example.com;
ssl_certificate /etc/ssl/certs/nanobot.example.com.crt;
ssl_certificate_key /etc/ssl/private/nanobot.example.com.key;
location / {
proxy_pass http://localhost:18790;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
💼 Professional Services: Need expert help with your Nanobot Docker deployment? We offer consulting, training, and support. Contact our team →