Nanobot - Guia Docker

1. Docker vs VPS Direto

Comparacao lado a lado: instalar direto na VPS versus usar Docker.

VPS Direto (manual)

# Instalar dependencias do sistema
sudo apt update
sudo apt install python3.12 python3.12-venv nodejs npm

# Criar e ativar ambiente virtual
python3.12 -m venv .venv
source .venv/bin/activate

# Instalar o nanobot
pip install .

# Configurar
nanobot onboard

# Iniciar manualmente
nanobot gateway

6 passos manuais

Precisa instalar Python, Node, venv manualmente
Ambiente virtual necessario
Se a VPS reiniciar, precisa iniciar de novo
Sem limites de recursos automaticos

Docker (automatico)

# Clonar e iniciar
git clone https://github.com/inematds/nanobot.git
cd nanobot
docker compose up -d

# Configurar (apenas primeira vez)
docker compose exec nanobot nanobot onboard

2 comandos

Python, Node, dependencias ja vem no container
Sem venv — tudo isolado por natureza
Reinicia automaticamente (unless-stopped)
Limites de RAM/CPU configurados

Resumo

Com Docker, o Dockerfile automatiza toda a instalacao. Voce so precisa de docker compose up -d e o container ja sai rodando com Python 3.12, Node.js 20, todas as dependencias instaladas, usuario non-root, e o gateway iniciado automaticamente.

2. Passo a Passo

Clonar o repositorio Baixe o codigo fonte do GitHub:

git clone https://github.com/inematds/nanobot.git && cd nanobot

Build e start com Docker Compose Um unico comando faz tudo:

docker compose up -d

A flag -d significa detached (modo desacoplado) — o container roda em segundo plano e voce recupera o terminal. O que acontece internamente durante o build:

Etapa	Comando no Dockerfile	O que faz
Imagem base	`FROM python:3.12-bookworm-slim`	Usa Python 3.12 com Debian slim como base (imagem otimizada com `uv` integrado)
Node.js	`apt-get install nodejs`	Instala Node.js 20 para a bridge do WhatsApp
Usuario	`useradd -m nanobot`	Cria usuario non-root por seguranca (nunca roda como root)
Python deps	`uv pip install --system .`	Instala todas as dependencias Python sem precisar de venv (usa `uv` que e 10-100x mais rapido que pip)
WhatsApp bridge	`npm install && npm run build`	Compila a bridge Node.js para WhatsApp (Baileys)
Diretorios	`mkdir -p ~/.nanobot/...`	Cria toda a estrutura de pastas: workspace, sessions, memory, skills, cron, history
Inicializacao	`CMD ["gateway"]`	Quando o container inicia, roda `nanobot gateway` automaticamente

Rodar o onboard (primeira vez) O assistente interativo de configuracao:

docker compose exec nanobot nanobot onboard

Esse comando entra no container e roda o nanobot onboard, que guia voce passo a passo para configurar provider (API key), modelo, e canal de chat (Telegram, Discord, etc.).

Adicionar/editar configuracao Se precisar editar a configuracao manualmente, existem 3 opcoes:

Opcao A: Copiar arquivo para dentro do container

Primeiro, crie o arquivo config.json na sua maquina local:

{
  "llm": {
    "provider": "openrouter",
    "model": "openrouter/qwen/qwen3-coder-next",
    "api_key": "sk-or-v1-SEU-TOKEN-AQUI"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "1234567890:ABCdefGHI-seu-token-bot-telegram",
      "allowFrom": ["seu_user_id_aqui"]
    }
  }
}

Depois, copie para dentro do container:

docker compose cp config.json nanobot:/home/nanobot/.nanobot/config.json

Opcao B: Editar dentro do container

Entre no container e edite diretamente:

# Entrar no container
docker compose exec nanobot bash

# Editar a configuracao (nano ja disponivel no container)
nano ~/.nanobot/config.json

# Quando terminar, sair do container
exit

Opcao C: Variaveis de ambiente no docker-compose.yml

Adicione as chaves diretamente no docker-compose.yml:

services:
  nanobot:
    build: .
    environment:
      - NANOBOT_PROVIDERS__OPENROUTER__API_KEY=sk-or-v1-SEU-TOKEN
      - NANOBOT_PROVIDERS__ANTHROPIC__API_KEY=sk-ant-SEU-TOKEN
      - NANOBOT_CHANNELS__TELEGRAM__TOKEN=1234567890:ABCdef
      - TZ=America/Sao_Paulo

Vantagem: as chaves ficam no arquivo compose e nao precisam ser copiadas para dentro do container. Desvantagem: ficam visiveis no arquivo YAML (nao commitar no git!).

Reiniciar para aplicar a configuracao Apos alterar a configuracao, reinicie o container:

docker compose restart

Verificar se esta funcionando Confira os logs, status e envie uma mensagem de teste:

# Ver os logs em tempo real
docker compose logs -f nanobot

# Verificar o status do nanobot
docker compose exec nanobot nanobot status

# Enviar mensagem de teste (se configurou Telegram)
# Basta mandar uma mensagem no Telegram para o bot!

Nos logs, procure por linhas como:

INFO  Gateway started on port 18790
INFO  TelegramChannel connected
INFO  Agent loop running

Se aparecerem erros, verifique se o config.json tem as chaves corretas e se o token do Telegram esta valido.

3. Comandos do Dia a Dia

Tabela de referencia rapida para operacoes comuns:

Acao	Comando	Descricao
Iniciar	`docker compose up -d`	Inicia o container em segundo plano (cria se nao existir)
Parar	`docker compose stop`	Para o container sem remover (dados preservados)
Reiniciar	`docker compose restart`	Para e inicia novamente (aplica mudancas de config)
Ver logs	`docker compose logs -f nanobot`	Mostra logs em tempo real (`-f` = follow). `Ctrl+C` para sair
Status	`docker compose ps`	Mostra se o container esta rodando, porta, e tempo de uptime
Entrar no container	`docker compose exec nanobot bash`	Abre um terminal bash dentro do container
Enviar mensagem	`docker compose exec nanobot nanobot send "Ola!"`	Envia uma mensagem diretamente pelo CLI
Atualizar codigo	`git pull && docker compose up -d --build`	Baixa codigo novo do GitHub e reconstroi o container
Remover tudo	`docker compose down`	Remove container (dados no volume sao preservados)
Remover tudo + dados	`docker compose down -v`	Remove container E o volume de dados (perda permanente!)

4. Onde Ficam os Dados

Comparacao entre instalacao direta na VPS e via Docker:

Item	VPS Direto	Docker
Codigo fonte	`~/nanobot/` (onde voce clonou)	`/app/` dentro do container
Configuracao	`~/.nanobot/config.json`	`/home/nanobot/.nanobot/config.json` (no volume `nanobot-data`)
Sessoes	`~/.nanobot/sessions/`	`/home/nanobot/.nanobot/sessions/` (no volume)
Workspace	`~/.nanobot/workspace/`	`/home/nanobot/.nanobot/workspace/` (no volume)
Venv necessario?	Sim — precisa criar e ativar	Nao — container ja e isolado
Sobrevive reboot?	Depende — precisa de systemd/cron	Sim — `restart: unless-stopped`
Limites de recursos?	Nao — precisa configurar manualmente	Sim — 2GB RAM, 2 CPUs (no compose)

Volume persistente

Todos os dados do nanobot (config, sessoes, memoria, workspace, cron, historico) ficam no volume Docker nanobot-data. Isso significa que mesmo se voce destruir e recriar o container (docker compose down && docker compose up -d), seus dados continuam intactos. Apenas docker compose down -v remove o volume (e os dados com ele).

5. Vantagens do Docker

Auto-restart

Com restart: unless-stopped, o container reinicia automaticamente se o processo cair, se houver um erro inesperado, ou se a VPS reiniciar. Voce so precisa parar manualmente se quiser.

Isolamento total

O nanobot roda num ambiente completamente separado do seu sistema. As dependencias do container nao interferem nas suas, e vice-versa. Se algo der errado dentro do container, seu sistema nao e afetado.

Limites de recursos

O docker-compose.yml ja vem configurado com limites seguros:

Memoria: maximo 2GB (reserva minima de 512MB)
CPU: maximo 2 nucleos
Tmpfs: /tmp limitado a 100MB

Isso impede que um bug ou loop infinito consuma todos os recursos da sua VPS.

Seguranca (non-root + no-new-privileges)

O container roda como usuario nanobot (nao root), e a flag no-new-privileges:true impede que qualquer processo dentro do container eleve seus privilegios. Mesmo que alguem explorasse uma vulnerabilidade, nao conseguiria virar root.

Volume persistente

O volume nanobot-data mantem todos os dados entre restarts, rebuilds e atualizacoes. Voce pode atualizar o codigo (git pull && docker compose up -d --build) sem perder nenhuma configuracao, sessao ou memoria.

Healthcheck integrado

O Dockerfile inclui um healthcheck que roda nanobot status a cada 30 segundos. O Docker monitora isso e pode reiniciar o container se ele ficar "unhealthy". Voce pode ver o status de saude com docker compose ps.

6. docker-compose.yml Explicado

O arquivo completo com comentarios explicando cada linha:

services:
  nanobot:
    build: .                          # Constroi a imagem usando o Dockerfile na raiz
    container_name: nanobot           # Nome fixo do container (facilita comandos)
    restart: unless-stopped           # Reinicia sempre, exceto se voce parar manualmente

    ports:
      - "127.0.0.1:18790:18790"      # Expoe a porta do gateway apenas no localhost
                                      # (127.0.0.1 = nao acessivel externamente)

    volumes:
      # Volume nomeado que persiste TODOS os dados do nanobot:
      # config.json, sessoes, workspace, memoria, cron, historico
      - nanobot-data:/home/nanobot/.nanobot

    environment:
      # Opcional: passar API keys via variaveis de ambiente
      # (alternativa ao config.json)
      # - NANOBOT_PROVIDERS__OPENROUTER__API_KEY=sk-or-xxx
      # - NANOBOT_PROVIDERS__ANTHROPIC__API_KEY=sk-ant-xxx
      - TZ=America/Sao_Paulo          # Fuso horario para cron e logs

    # Limites de recursos (protecao contra consumo excessivo)
    deploy:
      resources:
        limits:
          memory: 2G                   # Maximo 2GB de RAM
          cpus: "2.0"                  # Maximo 2 nucleos de CPU
        reservations:
          memory: 512M                 # Minimo 512MB reservados

    # Seguranca: impede escalacao de privilegios
    security_opt:
      - no-new-privileges:true         # Nenhum processo pode ganhar privilegios extras

    read_only: false                   # Permite escrita (necessario para sessoes/workspace)

    tmpfs:
      - /tmp:size=100M                 # /tmp em memoria, limitado a 100MB

# Volume nomeado (persiste dados independente do container)
volumes:
  nanobot-data:
    driver: local                      # Armazenamento local no disco da VPS

Dockerfile resumido

Para referencia, o que o Dockerfile faz em cada etapa:

# 1. Imagem base com Python 3.12 + uv (instalador rapido de pacotes)
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim

# 2. Instala Node.js 20 (necessario para a bridge WhatsApp)
RUN apt-get update && apt-get install -y nodejs ...

# 3. Cria usuario non-root por seguranca
RUN useradd -m -s /bin/bash nanobot

# 4. Instala dependencias Python (cache otimizado em camadas)
COPY pyproject.toml README.md LICENSE ./
RUN uv pip install --system --no-cache .

# 5. Copia codigo fonte e reinstala
COPY nanobot/ nanobot/
COPY bridge/ bridge/
RUN uv pip install --system --no-cache .

# 6. Compila a bridge WhatsApp
RUN npm install && npm run build

# 7. Cria estrutura de diretorios com permissoes corretas
RUN mkdir -p /home/nanobot/.nanobot/workspace/memory \
             /home/nanobot/.nanobot/workspace/skills \
             /home/nanobot/.nanobot/sessions \
             /home/nanobot/.nanobot/cron \
             /home/nanobot/.nanobot/history && \
    chown -R nanobot:nanobot /home/nanobot/.nanobot

# 8. Troca para usuario non-root
USER nanobot

# 9. Healthcheck automatico a cada 30s
HEALTHCHECK --interval=30s --timeout=5s \
    CMD nanobot status || exit 1

# 10. Comando padrao: inicia o gateway
ENTRYPOINT ["nanobot"]
CMD ["gateway"]