skorokithakis/stavrobotUn asistente personal de IA con enfoque en seguridad.
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 buenas características de un asistente de IA, pero se enfoca en el aislamiento, la separación y los permisos mínimos. Es ligero y se despliega con solo un docker compose up.
uv, aislado del entorno anfitrión.Instalación asistida por IA: Dile a tu IA de código (Claude Code, Cursor, Windsurf, etc.) que obtenga y siga https://stavrobot.stavros.io/INSTALL.md — te guiará a través de toda la configuración de forma interactiva.
Instalación manual:
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 ID de chat).
Copia env.example a .env y cambia POSTGRES_PASSWORD por algo seguro y TZ por tu zona horaria.
Copia config.example.toml a data/main/config.toml y completa los campos obligatorios: apiKey, password, publicHostname, [owner].name, [owner].telegram (tu ID de chat) y [telegram].botToken. Todo lo demás en el archivo es opcional.
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, correo electrónico y otras opciones.
config.example.toml a data/main/config.toml.authFile (o apiKey) y publicHostname. Todo lo demás es opcional.env.example a .env y establece tu zona horaria (TZ). Las credenciales de Postgres y otras configuraciones del entorno también se pueden sobrescribir allí. Siempre establece POSTGRES_PASSWORD como algo seguro — el valor predeterminado es un marcador de posición débil y no debe usarse en producción.Stavrobot puede apuntar a cualquier punto final compatible con OpenAI (Ollama, LiteLLM, vLLM, etc.) o a un proxy personalizado compatible con Anthropic configurando baseUrl en config.toml. Consulta config.example.toml para los campos obligatorios y ejemplos de configuración.
La aplicación admite dos modos de autenticación: clave API o OAuth.
apiKey en config.toml. No se necesita iniciar ni cerrar sesión.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 compatible con Pi.
<tu-hostname>/login en un navegador. Sigue las indicaciones en la página y las credenciales se guardan en el archivo de autenticación. Si la autenticación caduca mientras el bot está funcionando, te envía un mensaje con la URL de inicio de sesión a través de tu plataforma de mensajería.authFile. El bot detectará la falta de credenciales en el próximo mensaje y te pedirá que inicies sesión nuevamente.El contenedor coder es opcional (solo es necesario para la función de autoprogramación). Usa Claude Code con autenticación por suscripción (OAuth), separada de la clave API de la aplicación principal.
Los perfiles de Docker Compose están separados por comas, por lo que puedes combinarlos (por ejemplo, COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES en tu archivo .env para incluir coder (por ejemplo, COMPOSE_PROFILES=coder, o COMPOSE_PROFILES=signal,coder si también estás usando Signal).docker compose --profile coder up --builddocker compose exec -u coder coder claude (te pedirá que inicies sesión si no lo has hecho).[coder].model en tu configuración a un alias de modelo de Claude Code (sonnet, opus o haiku).Signal requiere un número de teléfono separado — no el tuyo personal. Sirve una SIM prepaga o un número VoIP.
COMPOSE_PROFILES=signal en tu archivo .env para habilitar el contenedor 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)' — escanea el código QR con tu teléfono (Signal > Configuración > Dispositivos vinculados).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +TU_NÚMERO register', luego verifica con docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +TU_NÚMERO verify CÓDIGO'.[signal].account en tu configuración.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:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
[telegram].botToken en tu configuración.[owner].telegram en tu configuración./settings.WhatsApp requiere un número de teléfono separado, ya que de lo contrario te estarías enviando mensajes a ti mismo, lo cual no funciona realmente.
WhatsApp usa Baileys, una biblioteca no oficial de WhatsApp Web que se vincula como un dispositivo complementario (como WhatsApp Web). No se necesita un número de teléfono separado: se vincula a tu cuenta de WhatsApp existente.
Riesgo: Baileys usa una API no oficial. WhatsApp puede prohibir cuentas que la usen. Úsalo bajo tu propio riesgo.
[whatsapp] a tu config.toml (consulta config.example.toml para el formato).docker compose up --builddocker compose logs -f app)../data/whatsapp./settings.El correo electrónico usa un Cloudflare Email Worker para la entrega entrante y SMTP para la saliente. Consulta
config.example.toml para el código completo del worker y las instrucciones detalladas de configuración.
[email] a tu config.toml con las credenciales SMTP y un webhookSecret aleatorio.config.example.toml) y establece las variables de entorno WEBHOOK_URL y WEBHOOK_SECRET en el worker./settings.docker compose up --build
La API está disponible en http://localhost:10567/chat.
Nota: Docker Compose solo expone la aplicación en localhost:10567. Para hacerla accesible externamente (necesario para los webhooks de Telegram/Signal y la configuración de publicHostname), configura un proxy inverso (por ejemplo, Nginx, Caddy) que apunte a localhost:10567. También puedes exponer el puerto directamente, pero no se recomienda ya que el tráfico no estará cifrado.
Requiere Node.js >= 20 y una instancia de PostgreSQL en ejecución.
npm install && npm run build && npm start
Nota: La ejecución de Python y la integración con Signal solo funcionan dentro de los contenedores Docker.
Stavrobot tiene un sistema de conocimiento de tres niveles: recuerdos, un bloc de notas y la base de datos. El bot los gestionará bastante bien por sí solo, pero es importante que tú los conozcas porque querrás ayudarlo a usarlos correctamente.
Los recuerdos se inyectan siempre directamente en el prompt del sistema. Debes ser moderado con ellos, ya que se incluyen en el contexto cada vez, y tener muchos puede aumentar el contexto. Un ejemplo de un buen recuerdo sería "al usuario le gusta chatear en un estilo informal.", algo que el bot debería saber siempre, incluso si eso cuesta en longitud adicional de contexto.
El bloc de notas es donde el bot guarda conocimientos a los que se accede con menos frecuencia, pero conocimientos que pertenecen a un tema. Las entradas del bloc de notas tienen un título y un cuerpo, y el título se inyecta en el contexto automáticamente. Úsalo para cosas importantes, pero menos frecuentes, que generalmente pertenecen a un tema específico.
Por ejemplo, una buena entrada del bloc de notas sería "preferencias alimentarias", con detalles sobre lo que te gusta comer, cuándo, etc. El bot verá que hay un tema "preferencias alimentarias", pero no cargará el texto real en el contexto automáticamente, solo accederá a él cuando sea necesario.
Cuando estés hablando con el bot sobre comida, sabrá que hay una entrada del bloc de notas "preferencias alimentarias" que puede consultar, y generalmente lo hará por sí solo.
La base de datos es el tercer nivel, para datos estructurados o masivos que no pertenecen a recuerdos ni al bloc de notas. El bot tiene acceso completo de lectura/escritura a PostgreSQL a través de SQL sin restricciones, por lo que puede crear tablas, ejecutar consultas y almacenar cualquier cosa. Úsalo para cosas como listas, registros, datos estructurados o cualquier dato que sea mejor consultar que leer como prosa.
El bot generalmente sabrá lo suficiente qué usar cuándo, pero a veces querrás decirle explícitamente qué información poner dónde.
Stavrobot puede enviar mensajes a personas en tu nombre a través de Signal, Telegram, WhatsApp o correo electrónico. ¿Necesitas coordinar una cena con un amigo? Dile al bot que encuentre un horario que funcione para ambos, y les enviará un mensaje, negociará una fecha y la pondrá en tu calendario. ¿Quieres organizar una cita, coordinar una salida en grupo o preguntarle algo a alguien mientras estás ocupado? Solo dile al bot lo que necesitas y con quién hablar.
El bot crea un subagente dedicado para cada conversación, con sus propias instrucciones y contexto, para que pueda gestionar el intercambio con la otra persona sin saturar tu chat principal. Cuando la tarea está completa, deshabilita el contacto y te informa.
Para mantener las cosas seguras, la mensajería requiere dos cosas antes de que el bot pueda hablar con alguien:
/settings y agrega su número de teléfono
(Signal o WhatsApp) o ID de chat (Telegram). Este es un paso único por persona. El
bot no puede modificar esta lista ni enviar mensajes a nadie que no esté en ella, pase lo que pase.Un flujo típico: agregas el número de teléfono de tu amigo a la lista de permitidos a través de /settings una vez,
luego le dices al bot "encuentra un horario para cenar con Alex la próxima semana". El bot crea un registro
de contacto para Alex, crea un subagente, le envía un mensaje a Alex por Signal, intercambia mensajes
para encontrar una fecha y te informa el resultado.
Las habilidades son archivos de instrucciones en texto plano que le enseñan al bot nuevas capacidades, como crear tablas, almacenar conocimiento, hacer páginas o seguir flujos de trabajo específicos. No son código; son instrucciones en lenguaje natural que el bot lee y sigue.
Para instalar el sistema de habilidades, dile al bot que obtenga
https://stavrobot.stavros.io/skills/bootstrap.md y siga sus instrucciones.
Una lista completa de habilidades disponibles está en
https://stavrobot.stavros.io/skills/index.md. Para instalar una habilidad, solo dile al bot que
la obtenga e instale desde esa URL. El bot te mostrará lo que hace la habilidad y te pedirá confirmación
antes de continuar.
Los archivos de habilidades residen en la rama pages de este repositorio (servida a través de Cloudflare Pages). Para
contribuir con una habilidad, agrega un archivo markdown a skills/ en esa rama. Cada archivo de
habilidad tiene un front matter YAML con title, description, version y un author
opcional, seguido de las instrucciones en lenguaje plano en el cuerpo. Consulta
SKILL-AUTHORING.md para la guía completa de autoría. Envía un PR
contra la rama pages.
Consulta PLUGIN.md para todo lo que necesitas saber para crear un plugin de Stavrobot. El mismo documento sirve como referencia tanto para humanos como para LLMs.
Los plugins son bastante necesarios para habilitar funcionalidades básicas del bot, como la capacidad de "oír" notas de voz, enviar notas de voz, conocer lugares a tu alrededor, buscar en la web, etc.
Estas capacidades no se proporcionan de serie para darte la capacidad de personalizar tu bot como quieras. Deberías instalar plugins, de lo contrario te faltarán funcionalidades cruciales.
Puedes encontrar algunos plugins de primer nivel aquí:
Tres contenedores Docker principales: app (servidor TypeScript, expone POST /chat, maneja webhooks de Telegram en POST /telegram/webhook, maneja webhooks de correo entrante en POST /email/webhook y ejecuta WhatsApp en proceso a través de Baileys), postgres (PostgreSQL 17 para estado persistente) y plugin-runner (servidor Node.js — lista, inspecciona y ejecuta plugins, tanto creados localmente como instalados por git). Un contenedor opcional coder (agente headless de Claude Code para crear y modificar plugins editables) se habilita a través del perfil coder de Docker Compose. El agente principal puede crear subagentes, cada uno con su propio historial de conversación, prompt del sistema y lista blanca de herramientas. Los interlocutores son registros de contacto asignados a agentes para el enrutamiento de mensajes entrantes.