Stavrobot

Stavrobot es un asistente personal de IA construido con el principio de "todo el acceso que un asistente de IA necesita, y nada más".

Tiene todas las características agradables de un asistente de IA, pero se centra en el sandboxing, el aislamiento y los permisos mínimos. Es ligero y se despliega con solo un docker compose up.

Características

• Seguro. Todo se ejecuta en un contenedor, tu sistema operativo anfitrión es completamente invisible para la IA. La IA no ve ningún secreto a menos que tú quieras que lo vea.
• Ligero. No ejecuta un contenedor por componente. Todos los plugins se ejecutan en un único contenedor, separados por permisos de Unix.
• Usa cualquier modelo que quieras. Local, OpenRouter, Anthropic/OpenAI. Lo que sea que Pi soporte, el bot puede usarlo.
• Integración con Signal/Telegram/WhatsApp/Email. Mensajería bidireccional, con formato, adjuntos, etc.
• Integración con Pebble Index. Las grabaciones del anillo se pueden encolar directamente para el agente.
• Conocimiento de tres niveles. Recuerda todo sin desbordar su contexto. Recupera datos de su memoria de forma inteligente y transparente.
• Bajo uso de tokens. Se han hecho varias optimizaciones para ser ligero en el uso de tokens. Incluso usa TOON internamente.
• Plugins. Instala plugins y amplía las capacidades de Stavrobot simplemente dándole una URL de repositorio git. Los plugins están aislados entre sí — cada uno se ejecuta como un usuario de sistema dedicado sin acceso a los archivos o la configuración de otros plugins.
• Subagentes. El agente principal puede crear subagentes con su propio contexto de conversación, prompt de sistema y acceso restringido a herramientas. Útil para hablar con personas externas para completar tareas o arreglar cosas, mientras se tiene un búfer entre la persona externa y el agente principal.
• Autoprogramación. El agente puede programarse y extenderse a sí mismo.
• Ejecución de Python en sandbox. Python arbitrario con dependencias de pip mediante uv, aislado del entorno anfitrión.
• Programación de tareas. El agente puede programar sus propias tareas recurrentes o puntuales.

Inicio rápido

Instalación asistida por IA: Dile a tu IA de programación (Claude Code, Cursor, Windsurf, etc.) que obtenga y siga https://stavrobot.stavros.io/INSTALL.md — te guiará por toda la configuración de forma interactiva.

Instalación manual:

1. Envía un mensaje a @BotFather en Telegram para crear un bot y copia el token. Envía un mensaje a @userinfobot para obtener tu ID de usuario de Telegram (se usa como el chat ID).

2. Copia env.example a .env y cambia POSTGRES_PASSWORD por algo seguro y TZ por tu zona horaria.

3. Copia config.example.toml a data/main/config.toml y rellena los campos requeridos: apiKey, password, publicHostname, [owner].name, [owner].telegram (tu chat ID) y [telegram].botToken. Todo lo demás en el archivo es opcional.

4. docker compose up --build

Eso es todo. Envía un mensaje a tu bot en Telegram y responderá. Consulta las secciones detalladas de configuración a continuación para Signal, WhatsApp, email y otras opciones.

Configuración

Config

1. Copia config.example.toml a data/main/config.toml.
2. Rellena las claves de API y los ajustes. El archivo de ejemplo tiene comentarios que explican cada sección.
3. Como mínimo, establece authFile (o apiKey) y publicHostname. Todo lo demás es opcional.
4. Copia env.example a .env y establece tu zona horaria (TZ). Las credenciales de Postgres y otros ajustes de entorno también se pueden sobrescribir ahí. Establece siempre POSTGRES_PASSWORD con algo seguro — el valor por defecto es un marcador de posición débil y no debe usarse en producción.

Editor de config

Después de que la aplicación arranque, abre /settings/config para editar config.toml en el navegador. La página está protegida por HTTP Basic Auth y muestra la configuración sin procesar, incluidos los secretos que contenga. Un guardado válido crea una única copia de seguridad <CONFIG_PATH>.bak, guarda el nuevo contenido y reinicia la aplicación; esto interrumpe cualquier turno del agente en curso.

plugin-runner, coder, signal-bridge y python-runner leen config.toml solo cuando arrancan. Los cambios que les afectan, como la contraseña, requieren reiniciar manualmente esos contenedores.

Endpoints personalizados y compatibles con OpenAI

Stavrobot se puede apuntar a cualquier endpoint compatible con OpenAI (Ollama, LiteLLM, vLLM, etc.) o a un proxy personalizado compatible con Anthropic estableciendo baseUrl en config.toml. Consulta config.example.toml para los campos requeridos y ejemplos de configuración. Establece reasoning = true solo para modelos que soporten thinking, ya que es lo que hace que thinkingLevel se aplique en un endpoint personalizado.

Autenticación

La aplicación soporta dos modos de autenticación: clave de API u OAuth.

• Clave de API: Establece apiKey en config.toml. No se necesita iniciar ni cerrar sesión.
• OAuth: Establece authFile en config.toml (una ruta donde se almacenarán las credenciales). La página de inicio de sesión funciona con cualquier proveedor de OAuth soportado por Pi.
  • Inicio de sesión: Visita <your-hostname>/login en un navegador. Sigue las indicaciones de la página y las credenciales se guardarán en el archivo de autenticación. Stavrobot elige el método de inicio de sesión headless del proveedor, así que nunca te redirige a un callback de localhost inalcanzable. Con Anthropic, después de seleccionar Authorize, Anthropic muestra un código, que copias y pegas en la página de inicio de sesión de Stavrobot. Los proveedores con un flujo de código de dispositivo muestran el código en la página de Stavrobot en su lugar, y tú lo escribes en el sitio del proveedor. Si la autenticación caduca mientras el bot está en ejecución, te envía un mensaje con la URL de inicio de sesión a través de tu plataforma de mensajería.
  • Cierre de sesión: Elimina el archivo en la ruta authFile. El bot detectará las credenciales faltantes en el siguiente mensaje y te pedirá que inicies sesión de nuevo.

Configuración de Claude Code

El contenedor coder es opcional (solo se necesita para la función de autoprogramación). Por defecto usa Claude Code con autenticación por suscripción (OAuth), separada de la clave de API de la aplicación principal. Para usar en su lugar un endpoint de API compatible con Anthropic, establece tanto [coder].apiKey como [coder].baseUrl en config.toml; Claude Code entonces los usa como ANTHROPIC_API_KEY y ANTHROPIC_BASE_URL. Los apiKey/baseUrl de nivel superior solo configuran el modelo de la aplicación principal y nunca afectan al coder. Establecer solo una de las dos claves de [coder] es un error de arranque.

Los perfiles de Docker Compose están separados por comas, así que puedes combinarlos (p. ej. COMPOSE_PROFILES=signal,coder).

1. Establece COMPOSE_PROFILES en tu archivo .env para incluir coder (p. ej. COMPOSE_PROFILES=coder, o COMPOSE_PROFILES=signal,coder si también usas Signal).
2. Inicia los contenedores: docker compose --profile coder up --build
3. Inicia sesión (omite este y el siguiente paso si estableciste [coder].apiKey/[coder].baseUrl): docker compose exec -u coder coder claude (te pedirá que inicies sesión si no lo has hecho).
4. Sigue el flujo de OAuth basado en navegador.
5. Establece [coder].model en tu config con un alias de modelo de Claude Code (sonnet, opus o haiku).

Configuración de Signal