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 interessantes de um assistente de IA, mas foca-se em sandboxing, isolamento e permissões mínimas. É leve e é implementado 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. As 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 fornecendo-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 irá 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 (este é 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 irá responder. Consulta 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 uma única cópia de segurança <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. Consulta config.example.toml para os campos obrigatórios e exemplos de configuração. Define reasoning = true apenas para modelos que suportam pensamento, pois é isso que faz com que thinkingLevel se aplique num endpoint personalizado.

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. O Stavrobot escolhe o método de login headless do fornecedor, por isso nunca és redirecionado para um callback localhost inacessível. Com a Anthropic, depois de selecionares Authorize, a Anthropic mostra um código, que copias e colas na página de login do Stavrobot. Os fornecedores com um fluxo de device-code mostram o código na página do Stavrobot, e tu escreve-lo no site do fornecedor. 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 irá detetar a ausência 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). Por predefinição usa o Claude Code com autenticação por subscrição (OAuth), separada da chave de API da aplicação principal. Para usar antes um endpoint de API compatível com Anthropic, define tanto [coder].apiKey como [coder].baseUrl em config.toml; o Claude Code usa-os então como ANTHROPIC_API_KEY e ANTHROPIC_BASE_URL. O apiKey/baseUrl de nível superior apenas configuram o modelo da aplicação principal e nunca afetam o coder. Definir apenas uma das duas chaves [coder] é um erro de arranque.

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 (salta este e o próximo passo se definiste [coder].apiKey/[coder].baseUrl): docker compose exec -u coder coder claude (ele irá 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.