skorokithakis/stavrobotUm assistente pessoal de IA com foco em segurança.
Stavrobot é um assistente pessoal de IA construído com o princípio de "todo o acesso que um assistente de IA precisa, e nada mais".
Ele tem todos os recursos interessantes de um assistente de IA, mas foca em sandboxing, isolamento e permissões mínimas. É leve e é implantado com apenas um docker compose up.
uv, isolado do ambiente host.Instalação assistida por IA: Diga ao seu coding AI (Claude Code, Cursor, Windsurf, etc.) para buscar e seguir https://stavrobot.stavros.io/INSTALL.md — ele guiará você por toda a configuração de forma interativa.
Instalação manual:
Envie uma mensagem para @BotFather no Telegram para criar um bot e copiar o token. Envie uma mensagem para @userinfobot para obter seu ID de usuário do Telegram (isso é usado como chat ID).
Copie env.example para .env e altere POSTGRES_PASSWORD para algo seguro e TZ para seu fuso horário.
Copie config.example.toml para data/main/config.toml e preencha os campos obrigatórios: apiKey, password, publicHostname, [owner].name, [owner].telegram (seu chat ID) e [telegram].botToken. Todo o resto no arquivo é opcional.
docker compose up --build
É isso. Envie uma mensagem para seu bot no Telegram e ele responderá. Veja as seções de configuração detalhada abaixo para Signal, WhatsApp, email e outras opções.
config.example.toml para data/main/config.toml.authFile (ou apiKey) e publicHostname. Todo o resto é opcional.env.example para .env e defina seu fuso horário (TZ). Credenciais do Postgres e outras configurações de ambiente também podem ser sobrescritas lá. Sempre defina POSTGRES_PASSWORD como algo seguro — o padrão é um placeholder fraco e não deve ser usado em produção.O Stavrobot pode ser apontado para qualquer endpoint compatível com OpenAI (Ollama, LiteLLM, vLLM, etc.) ou um proxy compatível com Anthropic personalizado, definindo baseUrl em config.toml. Veja config.example.toml para os campos obrigatórios e exemplos de configuração.
O aplicativo suporta dois modos de autenticação: chave de API ou OAuth.
apiKey em config.toml. Sem necessidade de login ou logout.authFile em config.toml (um caminho onde as credenciais serão armazenadas). A página de login funciona com qualquer provedor OAuth suportado pelo Pi.
<seu-hostname>/login em um navegador. Siga as instruções na página, e as credenciais são salvas no arquivo de autenticação. Se a autenticação expirar enquanto o bot está rodando, ele envia uma mensagem com a URL de login para você através da sua plataforma de mensagens.authFile. O bot detectará a falta de credenciais na próxima mensagem e solicitará que você faça login novamente.O container coder é opcional (necessário apenas para o recurso de autoprogramação). Ele usa Claude Code com autenticação por assinatura (OAuth), separada da chave de API do aplicativo principal.
Os perfis do Docker Compose são separados por vírgula, então você pode combiná-los (ex.: COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES no seu arquivo .env para incluir coder (ex.: COMPOSE_PROFILES=coder, ou COMPOSE_PROFILES=signal,coder se também estiver usando Signal).docker compose --profile coder up --builddocker compose exec -u coder coder claude (ele solicitará o login se você ainda não tiver feito).[coder].model na sua configuração para um alias de modelo Claude Code (sonnet, opus ou haiku).O Signal requer um número de telefone separado — não o seu pessoal. Um SIM pré-pago ou número VoIP funciona.
COMPOSE_PROFILES=signal no seu arquivo .env para ativar o container signal-bridge.docker compose --profile signal builddocker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — escaneie o código QR com seu telefone (Signal > Configurações > Dispositivos vinculados).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +SEU_NUMERO register', depois verifique com docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +SEU_NUMERO verify CODIGO'.[signal].account na sua configuração.docker compose up --build/settings.docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Envie a mensagem \"Olá do Stavrobot\" para meu número do Signal.'})}).then(r=>r.text()).then(console.log)"
[telegram].botToken na sua configuração.[owner].telegram na sua configuração./settings.O WhatsApp requer um número de telefone separado, caso contrário você estaria enviando mensagens para si mesmo, o que não funciona.
O WhatsApp usa Baileys, uma biblioteca não oficial do WhatsApp Web que vincula como um dispositivo complementar (como o WhatsApp Web). Nenhum número de telefone separado é necessário — ele vincula à sua conta WhatsApp existente.
Risco: Baileys usa uma API não oficial. O WhatsApp pode banir contas que a utilizam. Use por sua conta e risco.
[whatsapp] ao seu config.toml (veja config.example.toml para o formato).docker compose up --builddocker compose logs -f app)../data/whatsapp./settings.O email usa um Cloudflare Email Worker para entrega de entrada e SMTP para saída. Veja
config.example.toml para o código completo do worker e instruções detalhadas de configuração.
[email] ao seu config.toml com credenciais SMTP e um webhookSecret aleatório.config.example.toml) e defina as variáveis de ambiente WEBHOOK_URL e WEBHOOK_SECRET no worker./settings.docker compose up --build
A API está disponível em http://localhost:10567/chat.
Nota: O Docker Compose expõe o aplicativo apenas em localhost:10567. Para torná-lo acessível externamente (necessário para webhooks do Telegram/Signal e a configuração publicHostname), configure um proxy reverso (ex.: Nginx, Caddy) apontando para localhost:10567. Você também pode expor a porta diretamente, mas isso não é recomendado, pois o tráfego ficará sem criptografia.
Requer Node.js >= 20 e uma instância PostgreSQL em execução.
npm install && npm run build && npm start
Nota: A execução de Python e integração com Signal funcionam apenas dentro dos containers Docker.
O Stavrobot possui um sistema de conhecimento em três níveis: memórias, um rascunho e o banco de dados. Ele gerenciará isso razoavelmente bem por conta própria, mas é importante que você saiba disso porque você vai querer ajudar o bot a usá-los corretamente.
Memórias são sempre injetadas integralmente no prompt do sistema. Você deve ser econômico com elas, pois são incluídas no contexto toda vez, e ter muitas pode aumentar o contexto. Um exemplo de boa memória seria "o usuário prefere conversar em estilo informal.", algo que o bot deve saber sempre, mesmo que isso custe em comprimento adicional de contexto.
O rascunho é onde o bot mantém conhecimento menos acessado com frequência, mas conhecimento que pertence a um tópico. As entradas do rascunho têm um título e um corpo, e o título é injetado no contexto automaticamente. Use isso para coisas importantes, mas menos frequentemente necessárias, coisas que geralmente pertencem a um tópico específico.
Por exemplo, uma boa entrada de rascunho seria "preferências alimentares", com detalhes sobre o que você gosta de comer, quando, etc. O bot verá que há um tópico "preferências alimentares", mas não carregará o texto em si no contexto automaticamente, acessando-o apenas sob demanda.
Quando você estiver conversando com o bot sobre comida, ele saberá que há uma entrada de rascunho "preferências alimentares" que pode consultar, e geralmente fará isso por conta própria.
O banco de dados é o terceiro nível, para dados estruturados ou em massa que não pertencem a memórias ou ao rascunho. O bot tem acesso completo de leitura/escrita ao PostgreSQL via SQL irrestrito, então pode criar tabelas, executar consultas e armazenar qualquer coisa. Use isso para coisas como listas, logs, registros estruturados ou qualquer dado que seja melhor consultado do que lido como prosa.
O bot geralmente saberá bem o que usar quando, mas às vezes você vai querer dizer explicitamente a ele quais informações colocar onde.
O Stavrobot pode enviar mensagens para pessoas em seu nome via Signal, Telegram, WhatsApp ou email. Precisa marcar um jantar com um amigo? Diga ao bot para encontrar um horário que funcione para ambos, e ele enviará mensagens para eles, negociará uma data e colocará na sua agenda. Quer marcar um compromisso, coordenar um passeio em grupo ou perguntar algo a alguém enquanto estiver ocupado? Apenas diga ao bot o que você precisa e com quem falar.
O bot cria um subagente dedicado para cada conversa, com suas próprias instruções e contexto, para que possa lidar com a troca de mensagens com a outra pessoa sem poluir seu chat principal. Quando a tarefa é concluída, ele desativa o contato e reporta de volta para você.
Para manter as coisas seguras, o envio de mensagens requer duas coisas antes que o bot possa conversar com alguém:
/settings e adicione o número de telefone
(Signal ou WhatsApp) ou chat ID (Telegram). Este é um passo único por pessoa. O
bot não pode modificar esta lista ou enviar mensagens para quem não estiver nela, não importa o que.Um fluxo típico: você adiciona o número de telefone do seu amigo à lista de permissões via /settings uma vez,
depois diz ao bot "encontre um horário para jantar com o Alex na próxima semana". O bot cria um registro
de contato para Alex, cria um subagente, envia mensagem para Alex no Signal, troca mensagens
para encontrar uma data e reporta o resultado para você.
Habilidades são arquivos de instruções em texto simples que ensinam ao bot novas capacidades — coisas como criar tabelas, armazenar conhecimento, criar páginas ou seguir fluxos de trabalho específicos. Elas não são código; são instruções em linguagem natural que o bot lê e segue.
Para instalar o sistema de habilidades, diga ao bot para buscar
https://stavrobot.stavros.io/skills/bootstrap.md e seguir suas instruções.
Uma lista completa de habilidades disponíveis está em
https://stavrobot.stavros.io/skills/index.md. Para instalar uma habilidade, apenas diga ao bot para
buscá-la e instalá-la a partir dessa URL. O bot mostrará o que a habilidade faz e pedirá
confirmação antes de prosseguir.
Os arquivos de habilidades vivem no branch pages deste repositório (servido via Cloudflare Pages). Para
contribuir com uma habilidade, adicione um arquivo markdown em skills/ nesse branch. Cada arquivo de
habilidade tem front matter YAML com title, description, version e um author
opcional, seguido pelas instruções em linguagem simples no corpo. Veja
SKILL-AUTHORING.md para o guia completo de criação. Envie um PR
contra o branch pages.
Veja PLUGIN.md para tudo que você precisa saber para criar um plugin do Stavrobot. O mesmo documento serve como referência tanto para humanos quanto para LLMs.
Plugins são bastante necessários para habilitar funcionalidades principais do bot, como a capacidade de "ouvir" notas de voz, enviar notas de voz de volta, estar ciente de lugares ao seu redor, pesquisar na web, etc.
Essas capacidades não são fornecidas prontas para lhe dar a capacidade de personalizar seu bot como desejar. Você deve instalar plugins, no entanto, caso contrário, estará perdendo funcionalidades cruciais.
Você pode encontrar alguns plugins próprios aqui:
Três containers Docker principais: app (servidor TypeScript, expõe POST /chat, lida com webhooks do Telegram em POST /telegram/webhook, lida com webhooks de email recebidos em POST /email/webhook, e executa WhatsApp in-process via Baileys), postgres (PostgreSQL 17 para estado persistente) e plugin-runner (servidor Node.js — lista, inspeciona e executa plugins, tanto criados localmente quanto instalados via git). Um container opcional coder (agente headless do Claude Code para criar e modificar plugins editáveis) é ativado através do perfil coder do Docker Compose. O agente principal pode criar subagentes, cada um com seu próprio histórico de conversa, prompt de sistema e lista branca de ferramentas. Os interlocutores são registros de contato atribuídos a agentes para roteamento de mensagens recebidas.