nanobot — Guia de Instalacao

Parte 1 — Instalacao (so precisa fazer uma vez)

Este guia assume que voce tem um servidor Ubuntu limpo (22.04 ou superior) com acesso root. Se voce acabou de criar um VPS na DigitalOcean, Hetzner, Oracle Cloud, etc., siga passo a passo.

1. Conectar ao servidor via SSH

No seu computador local, abra o terminal e conecte:

ssh root@IP_DO_SERVIDOR

Substitua IP_DO_SERVIDOR pelo IP real do seu servidor (ex: ssh root@143.198.67.42).

2. Atualizar o sistema

Primeiro, atualize a lista de pacotes e instale as versoes mais recentes:

apt update && apt upgrade -y

3. Instalar ferramentas necessarias

apt install -y python3 python3-venv python3-pip git

4. Clonar o repositorio

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

Isso baixa todo o codigo do nanobot para a pasta /root/nanobot/ e entra nela.

5. Criar o ambiente virtual (venv)

python3 -m venv venv

6. Ativar o ambiente virtual

source venv/bin/activate

Depois de ativar, o prompt do terminal muda para mostrar que voce esta dentro do venv:

O (venv) no inicio confirma que a caixa esta ativa. A partir de agora, tudo que voce instalar com pip vai para dentro dessa caixa.

7. Instalar o nanobot

pip install -e .

8. Executar o onboard

nanobot onboard

O comando onboard cria a estrutura de diretorios que o nanobot precisa para funcionar:

~/.nanobot/
+-- config.json          ← Configuracao principal (criado vazio)
+-- sessions/            ← Pasta para historico de conversas
+-- workspace/           ← Area de trabalho do agente
    +-- AGENTS.md        ← Personalidade do agente
    +-- SOUL.md          ← Instrucoes profundas
    +-- USER.md          ← Informacoes sobre voce
    +-- memory/          ← Memoria persistente
        +-- MEMORY.md    ← Memoria de longo prazo

9. Editar a configuracao

nano ~/.nanobot/config.json

Cole o seguinte conteudo (ajustando as chaves):

{
  "llm": {
    "default_model": "openrouter/qwen/qwen3-coder",
    "api_key": "sk-or-v1-SUA_CHAVE_OPENROUTER_AQUI"
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "123456789:SEU_TOKEN_TELEGRAM_AQUI",
      "allowFrom": ["SEU_CHAT_ID_AQUI"]
    }
  }
}

Para salvar no nano: pressione Ctrl+O (salvar), Enter (confirmar), Ctrl+X (sair).

10. Proteger a configuracao

chmod 600 ~/.nanobot/config.json

O chmod 600 faz com que somente o dono (root) possa ler e escrever esse arquivo. Isso e importante porque o arquivo contem suas chaves de API — se qualquer usuario do servidor pudesse ler, suas chaves estariam expostas.

11. Configurar aliases no .bashrc

Abra o arquivo .bashrc:

nano ~/.bashrc

Adicione estas duas linhas no final do arquivo:

alias nb='cd /root/nanobot && source venv/bin/activate'
alias nbhelp='cd /root/nanobot && bash help.sh'

Depois salve (Ctrl+O, Enter, Ctrl+X) e carregue as mudancas:

source ~/.bashrc

12. Testar a instalacao

Verifique se tudo esta configurado corretamente:

nanobot status

Este comando mostra: modelo configurado, provider detectado, channels habilitados, e se as chaves sao validas.

Faca um teste rapido de comunicacao com a IA:

nanobot agent -m "Ola, estou testando. Responda com uma frase curta."

Se tudo estiver certo, voce vera a resposta da IA diretamente no terminal.

13. Iniciar o gateway

O gateway e o servidor que fica escutando mensagens dos channels (Telegram, etc.).

Modo foreground (para testar — voce ve os logs ao vivo, Ctrl+C para parar):

nanobot gateway

Modo background (para deixar rodando mesmo depois de fechar o terminal):

nohup python -m nanobot gateway > ~/.nanobot/gateway.log 2>&1 &

apt update && apt upgrade -y && apt install -y python3 python3-venv python3-pip git && \
cd /root && git clone https://github.com/inematds/nanobot.git && cd nanobot && \
python3 -m venv venv && source venv/bin/activate && pip install -e . && \
nanobot onboard && nano ~/.nanobot/config.json

Parte 2 — Uso Diario

Entendendo o source

Toda vez que voce conectar via SSH, o venv nao esta ativo. Voce precisa ativa-lo antes de usar o nanobot.

Scripts disponiveis

O nanobot inclui dois scripts auxiliares na raiz do projeto:

3 formas de ativar o ambiente

Escolha a que preferir — todas fazem a mesma coisa:

Tabela de comandos

Como atualizar o codigo

Quando houver uma atualizacao no repositorio:

# 1. Parar o gateway (se estiver rodando)
pkill -f 'nanobot gateway'

# 2. Ativar o ambiente (se nao estiver ativo)
nb

# 3. Baixar atualizacoes e reinstalar
git pull && pip install -e .

# 4. Reiniciar o gateway
nohup python -m nanobot gateway > ~/.nanobot/gateway.log 2>&1 &

Parte 3 — Estrutura de Diretorios

O nanobot usa duas pastas separadas. Entender a diferenca e fundamental:

/root/nanobot/                        ← CODIGO (repositorio git)
+-- nanobot/                          ← Codigo-fonte Python
|   +-- agent/                        ← Logica do agente (loop, tools, context)
|   +-- bus/                          ← Message bus (fila)
|   +-- channels/                     ← Telegram, Discord, WhatsApp...
|   +-- config/                       ← Schema e loader de configuracao
|   +-- providers/                    ← Conexao com IAs (LiteLLM)
|   +-- session/                      ← Gerenciador de sessoes
|   +-- cron/                         ← Agendador de tarefas
|   +-- heartbeat/                    ← Servico de heartbeat
|   +-- security/                     ← Rate limit, validacao
|   +-- skills/                       ← Skills embutidos
+-- venv/                             ← Ambiente virtual Python
+-- start.sh                          ← Script para ativar venv
+-- help.sh                           ← Guia rapido de comandos
+-- setup.py / pyproject.toml         ← Definicao do pacote
+-- config.json                       ← Exemplo de configuracao (NAO usar este!)
+-- docs/                             ← Documentacao (esta pagina)

/root/.nanobot/                       ← DADOS DE RUNTIME (seus dados pessoais)
+-- config.json                       ← SUA configuracao real (chaves, modelo, canais)
+-- gateway.log                       ← Log do gateway
+-- sessions/                         ← Historico de conversas (.jsonl)
|   +-- telegram_123456789.jsonl
+-- workspace/                        ← Area de trabalho do agente
    +-- AGENTS.md                     ← Personalidade do agente
    +-- SOUL.md                       ← Instrucoes profundas
    +-- USER.md                       ← Informacoes sobre voce
    +-- HEARTBEAT.md                  ← Instrucoes do heartbeat
    +-- memory/                       ← Memoria persistente
        +-- MEMORY.md                 ← Memoria de longo prazo
        +-- 2026-02-10.md             ← Notas do dia

Parte 4 — Resumo Visual

Fluxo: "Acabei de entrar via SSH"

  +------------------+
  |  ssh root@IP     |
  +--------+---------+
           |
           v
  +------------------+
  |  Digitar: nb     |
  |  (alias que      |
  |   ativa o venv)  |
  +--------+---------+
           |
           v
  +------------------+
  |  Prompt mostra   |
  |  (venv) root@... |
  +--------+---------+
           |
     +-----+------+
     |            |
     v            v
+---------+  +------------------+
| Checar  |  | Iniciar gateway  |
| status  |  +--------+---------+
| nanobot |           |
| status  |     +-----+------+
+---------+     |            |
                v            v
          +-----------+  +--------------------+
          | Foreground|  | Background         |
          | nanobot   |  | nohup python -m    |
          | gateway   |  | nanobot gateway    |
          |           |  | > gateway.log 2>&1 &|
          | (Ctrl+C   |  +--------------------+
          |  p/ parar)|
          +-----------+

Fluxo: "Quero parar / ver logs"

  +-------------------------+
  |  O que voce quer fazer? |
  +-----+----------+--------+
        |          |
        v          v
  +-----------+  +------------------+
  |  PARAR    |  |  VER LOGS        |
  +-----------+  +------------------+
        |                |
        v                v
  +-----------+  +------------------+
  | pkill -f  |  | tail -f          |
  | 'nanobot  |  | ~/.nanobot/      |
  |  gateway' |  | gateway.log      |
  +-----------+  |                  |
        |        | (Ctrl+C p/ sair  |
        v        |  do tail)        |
  +-----------+  +------------------+
  | Confirmar |
  | que parou:|
  | ps aux |  |
  | grep      |
  | nanobot   |
  +-----------+

Fluxo: "Quero atualizar o codigo"

  +-----------------------+
  |  1. Parar gateway     |
  |  pkill -f 'nanobot    |
  |  gateway'             |
  +----------+------------+
             |
             v
  +-----------------------+
  |  2. Ativar venv       |
  |  nb                   |
  +----------+------------+
             |
             v
  +-----------------------+
  |  3. Atualizar         |
  |  git pull &&          |
  |  pip install -e .     |
  +----------+------------+
             |
             v
  +-----------------------+
  |  4. Reiniciar         |
  |  nohup python -m      |
  |  nanobot gateway      |
  |  > gateway.log 2>&1 & |
  +-----------------------+