Stavrobot

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".

Tem todas as funcionalidades agradáveis de um assistente de IA, mas foca em sandboxing, isolamento e permissões mínimas. É leve e é implantado apenas com um docker compose up.

Funcionalidades

• Seguro. Tudo corre num contentor, o teu sistema operativo anfitrião é completamente invisível para a IA. A IA não vê quaisquer segredos a menos que tu queiras.
• Leve. Não corre um contentor por componente. Os plugins correm todos num único contentor, separados por permissões Unix.
• Usa qualquer modelo que queiras. Local, OpenRouter, Anthropic/OpenAI. O que quer que o Pi suporte, o bot pode usar.
• Integração com Signal/Telegram/WhatsApp/Email. Mensagens bidirecionais, com formatação, anexos, etc.
• Integração com Pebble Index. Gravações do anel podem ser colocadas diretamente na fila para o agente.
• Conhecimento em três níveis. Lembra-se de tudo sem rebentar o seu contexto. Recupera dados da sua memória de forma inteligente e transparente.
• Baixo consumo de tokens. Foram feitas várias otimizações para ser leve no consumo de tokens. Usa até TOON internamente.
• Plugins. Instala plugins e estende as capacidades do Stavrobot apenas dando-lhe um URL de repositório git. Os plugins estão isolados uns dos outros — cada um corre como um utilizador de sistema dedicado sem acesso aos ficheiros ou configuração de outros plugins.
• Subagentes. O agente principal pode criar subagentes com o seu próprio contexto de conversa, prompt de sistema e acesso restrito a ferramentas. Útil para falar com pessoas externas para completar tarefas ou combinar coisas, mantendo um buffer entre a pessoa externa e o agente principal.
• Auto-programação. O agente pode programar-se e estender-se a si próprio.
• Execução de Python em sandbox. Python arbitrário com dependências pip via uv, isolado do ambiente anfitrião.
• Agendamento. O agente pode agendar as suas próprias tarefas recorrentes ou pontuais.

Início rápido

Instalação assistida por IA: Diz à tua IA de programação (Claude Code, Cursor, Windsurf, etc.) para obter e seguir https://stavrobot.stavros.io/INSTALL.md — ela vai guiar-te por toda a configuração de forma interativa.

Instalação manual:

1. Envia mensagem ao @BotFather no Telegram para criar um bot e copia o token. Envia mensagem ao @userinfobot para obter o teu ID de utilizador do Telegram (isto é usado como o chat ID).

2. Copia env.example para .env e altera POSTGRES_PASSWORD para algo seguro e TZ para o teu fuso horário.

3. Copia config.example.toml para data/main/config.toml e preenche os campos obrigatórios: apiKey, password, publicHostname, [owner].name, [owner].telegram (o teu chat ID), e [telegram].botToken. Tudo o resto no ficheiro é opcional.

4. docker compose up --build

É isso. Envia mensagem ao teu bot no Telegram e ele vai responder. Vê as secções detalhadas de configuração abaixo para Signal, WhatsApp, email e outras opções.

Configuração

Config

1. Copia config.example.toml para data/main/config.toml.
2. Preenche as chaves de API e as definições. O ficheiro de exemplo tem comentários a explicar cada secção.
3. No mínimo, define authFile (ou apiKey) e publicHostname. Tudo o resto é opcional.
4. Copia env.example para .env e define o teu fuso horário (TZ). As credenciais do Postgres e outras definições de ambiente também podem ser substituídas aí. Define sempre POSTGRES_PASSWORD para algo seguro — o valor predefinido é um placeholder fraco e não deve ser usado em produção.

Editor de config

Depois de a aplicação arrancar, abre /settings/config para editar config.toml no navegador. A página está protegida por HTTP Basic Auth e mostra a configuração em bruto, incluindo quaisquer segredos que contenha. Uma gravação válida cria um único backup <CONFIG_PATH>.bak, grava o novo conteúdo e reinicia a aplicação; isto interrompe qualquer turno do agente em curso.

plugin-runner, coder, signal-bridge e python-runner leem config.toml apenas quando arrancam. Alterações que os afetem, como a password, exigem reiniciar manualmente esses contentores.

Endpoints personalizados e compatíveis com OpenAI

O Stavrobot pode ser apontado para qualquer endpoint compatível com OpenAI (Ollama, LiteLLM, vLLM, etc.) ou um proxy personalizado compatível com Anthropic definindo baseUrl em config.toml. Vê config.example.toml para os campos obrigatórios e configurações de exemplo.

Autenticação

A aplicação suporta dois modos de autenticação: chave de API ou OAuth.

• Chave de API: Define apiKey em config.toml. Não é necessário login nem logout.
• OAuth: Define authFile em config.toml (um caminho onde as credenciais serão armazenadas). A página de login funciona com qualquer fornecedor OAuth suportado pelo Pi.
  • Login: Visita <your-hostname>/login num navegador. Segue as instruções na página, e as credenciais são guardadas no ficheiro de autenticação. Se a autenticação expirar enquanto o bot está a correr, ele envia-te uma mensagem com o URL de login através da tua plataforma de mensagens.
  • Logout: Apaga o ficheiro no caminho authFile. O bot vai detetar a falta de credenciais na mensagem seguinte e pedir-te para iniciares sessão novamente.

Configuração do Claude Code

O contentor coder é opcional (necessário apenas para a funcionalidade de auto-programação). Usa o Claude Code com autenticação por subscrição (OAuth), separada da chave de API da aplicação principal.

Os perfis do Docker Compose são separados por vírgulas, por isso podes combiná-los (por exemplo, COMPOSE_PROFILES=signal,coder).

1. Define COMPOSE_PROFILES no teu ficheiro .env para incluir coder (por exemplo, COMPOSE_PROFILES=coder, ou COMPOSE_PROFILES=signal,coder se também estiveres a usar Signal).
2. Inicia os contentores: docker compose --profile coder up --build
3. Inicia sessão: docker compose exec -u coder coder claude (ele vai pedir-te para iniciares sessão se ainda não o fizeste).
4. Segue o fluxo OAuth baseado no navegador.
5. Define [coder].model na tua config para um alias de modelo do Claude Code (sonnet, opus, ou haiku).

Configuração do Signal

O Signal requer um número de telefone separado — não o teu pessoal. Um SIM pré-pago ou número VoIP funciona.