Pepedocs

Introducción

Pepe ejecuta agentes de IA en tu propia máquina. Describe quiénes son, conecta cualquier modelo compatible con OpenAI y deja que hagan trabajo de verdad con herramientas. Sin servidor de base de datos, sin ataduras a un proveedor.

Qué es Pepe

Pepe ejecuta agentes de IA en tu propia máquina o servidor. Describes un agente una vez (un nombre, sus instrucciones, las herramientas que puede usar y el modelo con el que piensa) y Pepe se encarga del resto: cuando llega una petición, el agente trabaja por pasos, usando sus herramientas, hasta tener una respuesta de verdad.

Los agentes viven mucho tiempo: conversaciones, canales, tareas en segundo plano, no peticiones sueltas. Pepe está construido en Elixir/OTP, una tecnología hecha exactamente para ese tipo de trabajo, así que un servidor modesto mantiene a todo un equipo de agentes funcionando en paralelo sin gastar mucha memoria ni CPU.

Ese bucle interno es la razón de ser de todo. Una simple llamada de chat devuelve texto. Un agente puede realmente hacer cosas: leer un archivo, ejecutar un comando, buscar en la web, llamar a tu API, y luego razonar sobre lo que encontró y continuar. Pepe te entrega ese bucle como un runtime terminado, en lugar de algo que tienes que armar a mano en cada proyecto.

pepe run "lee package.json y dime qué dependencias están desactualizadas"

Defines el comportamiento una vez, y el mismo agente queda accesible de cuatro formas: desde la terminal, mediante una API HTTP compatible con OpenAI, a través de un WebSocket con streaming, y desde canales de mensajería como Telegram y WhatsApp. También hay un panel web para navegar y conversar desde el navegador. Atiende cada caso de uso allí donde ya vive, sin crear un agente separado para cada canal.

El bucle de llamadas a herramientas

Este es el ciclo que Pepe ejecuta en cada turno:

  1. Envía la conversación, junto con las definiciones de herramientas del agente, al modelo.
  2. Si el modelo devuelve llamadas a herramientas, ejecuta cada una y recoge su salida.
  3. Añade el mensaje del asistente y los resultados de las herramientas a la conversación.
  4. Vuelve al paso 1. Se detiene cuando el modelo devuelve una respuesta simple, o cuando el agente alcanza su límite de seguridad max_iterations.

Por el camino, Pepe anuncia cada paso, para que cualquier superficie pueda mostrar el progreso en tiempo real: la respuesta a medida que llega en streaming (assistant_delta), cada llamada a herramienta y su resultado (tool_call, tool_result), la respuesta final (done) y los errores (error).

Las herramientas arriesgadas (cualquiera que ejecute un comando o escriba un archivo) pueden configurarse para pedirte permiso antes. Si te niegas, la herramienta nunca se ejecuta: el modelo solo recibe una breve nota de “denegado” (y se emite un evento tool_denied), de modo que un agente nunca actúa en silencio sobre tu máquina sin tu consentimiento.

Herramientas integradas. A cada agente se le pueden dar herramientas como bash, read_file, write_file, edit_file, list_dir, fetch_url y web_search. Eliges cuáles recibe cada agente al crearlo, así un bot de soporte y un agente de programación pueden tener capacidades muy distintas.

Las cinco superficies

Construyes un agente una vez. Pepe lo expone luego a través de la superficie que mejor encaje con la tarea. La configuración y la gestión, por su parte, ocurren de tres maneras: la CLI pepe, el panel web y por chat (hablando en lenguaje natural con un agente que posee la herramienta de gestión adecuada).

CLI

El comando pepe es la forma de configurar las cosas y de ejecutar agentes desde una terminal. Las ejecuciones puntuales transmiten su respuesta directamente a la salida estándar, y pepe chat abre una sesión interactiva que recuerda la conversación.

pepe run assistant "resume el git log de la última semana"
pepe chat assistant

Panel web

Ejecuta el servidor y abre el panel en un navegador para conversar con un agente, navegar por sesiones anteriores y gestionar agentes, conexiones a modelos, canales, tareas programadas, uso y trazas desde una interfaz de apuntar y hacer clic. En localhost está abierto por defecto; puedes protegerlo tras una contraseña de operador cuando lo expongas.

pepe serve --port 4000
# luego abre http://localhost:4000

API HTTP compatible con OpenAI

Arranca el servidor y Pepe habla el protocolo Chat Completions de OpenAI, así que cualquier SDK de OpenAI, LangChain o un simple curl pueden comunicarse con él sin adaptador. Sirve POST /v1/chat/completions y GET /v1/models.

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant",
    "messages": [{"role": "user", "content": "¿Qué archivos hay en este proyecto?"}]
  }'

Apunta un cliente de OpenAI existente a http://localhost:4000/v1 y el nombre del modelo pasa a ser el nombre de tu agente. Consulta la página de la API HTTP para streaming, eventos de herramientas y autenticación.

WebSocket

Para conversaciones en vivo, token a token, en una app web o móvil, conéctate por un WebSocket y suscríbete al tema de tu agente (agent:<name>). Recibes el texto del asistente a medida que se transmite, más eventos por cada llamada y resultado de herramienta. Los detalles y un ejemplo de cliente están en la página de la API.

Canales de mensajería

Pon el mismo agente frente a usuarios reales en las plataformas que ya usan. Pepe incluye pasarelas para Telegram, WhatsApp, Slack, Discord, Microsoft Teams y Google Chat, además de un webhook de entrada genérico para cualquier otra cosa. Cada canal se vincula a un agente y mantiene su propia memoria de conversación por usuario. Consulta la página de canales.

Definir un agente

Un agente no es más que un nombre, un prompt de sistema, una lista de herramientas y un modelo. Crea uno desde la CLI:

pepe agent add assistant \
  --prompt "Eres Pepe, un agente de programación útil." \
  --tools bash,read_file,write_file,edit_file,list_dir,fetch_url,web_search \
  --default

También puedes hacerlo en el panel web, en la página Agents, que incluye un formulario para la persona, el modelo y la selección de herramientas.

Hazlo por chat

Un agente que posee la herramienta manage_agent puede crear y dar forma a otros agentes directamente desde una conversación. Envíale un mensaje sencillo:

Tú: Crea un nuevo agente llamado “researcher” cuyo trabajo sea escarbar en la documentación y resumir hallazgos, y dale web_search y fetch_url.

El agente usa manage_agent para create el nuevo agente, definir su persona y añadir cada herramienta. manage_agent es una capacidad protegida: el agente solo puede tocar los agentes de su propia lista de permitidos, tiene la instrucción de confirmar los cambios contigo primero, y como es una herramienta arriesgada, cada llamada aún pasa por la barrera de permisos antes de que se escriba nada. Así ves el cambio propuesto y lo apruebas antes de que surta efecto.

Conectar un modelo

Pepe nunca incluye un modelo ni una clave. Lo apuntas a cualquier proveedor compatible con OpenAI mediante una conexión a un modelo:

pepe model add openrouter \
  --api-key '${OPENROUTER_API_KEY}' \
  --model openai/gpt-5-chat \
  --default

La página Models del panel hace lo mismo con un formulario, y puede probar una conexión antes de guardarla. Fíjate en ${OPENROUTER_API_KEY}: los secretos se guardan como referencias a variables de entorno y se expanden solo al leerse, así que tus claves nunca se escriben de vuelta en disco en texto plano.

Añadir un canal

Vincula un agente a un canal de mensajería para que la gente pueda hablarle donde ya está. Desde el panel, la página Channels te guía para conectar un bot y elegir con qué agente conversa. El canal mantiene entonces una memoria de conversación separada por usuario.

Hazlo por chat

Un agente que posee la herramienta manage_channel puede levantar un bot de Telegram desde una conversación:

Tú: Añade un bot de Telegram llamado “support-bot” que hable con el agente de soporte. El token está en la variable de entorno SUPPORT_BOT_TOKEN.

El agente usa manage_channel para añadir el bot y vincularlo al agente indicado. Esta capacidad está deliberadamente protegida: solo toca bots con nombre (nunca el predeterminado protegido), tiene la instrucción de confirmar los detalles contigo primero, y es una herramienta arriesgada, así que la llamada pasa por la barrera de permisos. Y algo crucial: le das el nombre de una variable de entorno que contiene el token, nunca el token en sí, de modo que el secreto nunca pasa por el chat ni por el modelo. Tras el cambio, el bot en marcha arranca en vivo, sin reiniciar.

Decisiones de arquitectura que simplifican el uso

Autoalojado, tus claves, tus datos

Pepe nunca incluye un modelo ni una clave de API. Lo ejecutas en tu propia máquina o servidor, y lo apuntas al proveedor que quieras. Nada de una conversación sale de tu infraestructura, salvo las llamadas que configures hacia el endpoint del modelo que elijas.

Independiente del modelo

Como cada proveedor se alcanza con el mismo protocolo Chat Completions de OpenAI, cambiar de modelo es un cambio de configuración, no de código. OpenAI, OpenRouter, Together, Groq, DeepSeek, Mistral y servidores locales como Ollama, LM Studio y vLLM funcionan todos igual. Una conexión a un modelo puede incluso listar modelos de reserva, así que un fallo transitorio (un límite de tasa, un error del servidor, un corte de red) en un proveedor pasa discretamente al siguiente, mientras que una clave errónea o una petición mal formada falla de inmediato en lugar de reintentar sin sentido.

Sin base de datos

Toda la configuración (conexiones a modelos, agentes, canales, programaciones) vive en un único archivo JSON en ~/.pepe/config.json, fácil de leer, editar y respaldar. No hay nada que instalar junto a Pepe ni nada que migrar. Los secretos se escriben como referencias ${ENV_VAR} y se expanden solo al leerse, así que tus claves nunca se escriben de vuelta en disco en texto plano.

{
  "models": {
    "openrouter": {
      "base_url": "https://openrouter.ai/api/v1",
      "api_key": "${OPENROUTER_API_KEY}",
      "model": "openai/gpt-5-chat"
    }
  }
}

Conversaciones aisladas

Cada conversación se ejecuta separada de todas las demás. Si una sale mal, el resto ni se entera: un solo turno defectuoso no puede tumbar tus otros agentes ni tus otras conversaciones.

Multi-cliente cuando la necesitas

El trabajo puede acotarse a un proyecto, aislando agentes, canales, modelos y uso por cliente. Si nunca lo activas, todo vive en el proyecto por defecto, al que recurre cada comando, y puedes ignorar los proyectos por completo.

A dónde ir después

Instalación →