Imagina escribir "¿Por qué mi app Node se está cayendo?" en un cuadro de chat, y obtener una respuesta que no es un resumen genérico de Stack Overflow -- sino un diagnóstico real, extraído de las métricas reales de tu servidor, los logs reales de tu despliegue y el estado real de tu contenedor. Eso es lo que construimos en un solo día.
El 23 de marzo de 2026, añadimos un AI gateway a sh0 que convierte a Claude en un ingeniero DevOps con conocimiento a nivel root de tu infraestructura. No un chatbot que adivina. Un agente que verifica. La arquitectura es inusual: la API de Anthropic vive en el backend de nuestro sitio web, pero las herramientas se ejecutan en el navegador del usuario, porque solo el navegador tiene acceso al servidor local sh0 del usuario. Esta división -- LLM del lado del servidor, ejecución del lado del cliente -- es la idea clave que hace que todo el sistema funcione.
Esta es la historia de cómo lo construimos: el gateway, las definiciones de herramientas, el bucle agéntico, el modelo de facturación y el system prompt que mantiene a Claude enfocado.
La arquitectura: tres capas, dos codebases
El sistema de IA abarca dos codebases separados:
- sh0-website (SvelteKit en sh0.dev) -- el gateway. Almacena la clave API de Anthropic, maneja autenticación, transmite respuestas, deduce créditos del monedero.
- sh0-core/dashboard (SPA Svelte 5 incrustada en el binario Rust) -- el cliente. Renderiza la interfaz de chat, ejecuta llamadas a herramientas contra la API local de sh0, envía resultados de vuelta.
El usuario nunca habla directamente con Anthropic. Cada mensaje fluye a través de nuestro gateway, que actúa como un proxy autenticado, medido y auditable.
El usuario escribe un mensaje
--> El dashboard envía POST a sh0.dev/api/ai/chat (autenticación Bearer)
--> El gateway valida la clave, verifica saldo del monedero
--> El gateway llama a la API de Messages de Anthropic (streaming)
--> El gateway emite eventos SSE de vuelta al dashboard
--> Si Claude devuelve bloques tool_use:
--> El gateway emite eventos SSE tool_call
--> El dashboard ejecuta herramientas contra la API local de sh0
--> El dashboard envía POST con resultados de herramientas al gateway
--> El gateway envía resultados a Claude, transmite siguiente respuesta
--> Repetir (máximo 10 iteraciones)
--> El gateway deduce tokens del monederoEste diseño tiene una ventaja no obvia: el gateway nunca necesita acceso al servidor del usuario. Solo necesita la clave API de Anthropic. El dashboard maneja todas las operaciones privilegiadas localmente. Esto significa que nunca enrutamos datos de infraestructura del usuario a través de nuestros servidores -- Claude los ve durante la conversación, pero solo almacenamos la respuesta de texto final, no las salidas crudas de herramientas.
El monedero prepago
Antes de enviar cualquier mensaje, el gateway verifica el monedero del usuario. El modelo de facturación es créditos prepago con un margen del 20% sobre el precio de lista de Anthropic. Los usuarios compran paquetes de créditos ($5, $20, $50, $100) con bonificaciones de volumen en paquetes más grandes. Los usuarios del plan Business pueden traer su propia clave (BYOK). Los usuarios BYOK omiten el monedero completamente.
Las 10 definiciones de herramientas
Definimos 10 herramientas en el formato de llamada de funciones de Anthropic, divididas en tres categorías:
Herramientas de lectura (ejecutadas por el dashboard contra la API local de sh0):
- list_apps -- todas las aplicaciones con estado, dominios y uso de recursos
- get_app_details -- información completa de la aplicación
- get_deployment_logs -- despliegues recientes con logs de compilación
- get_server_status -- CPU, memoria, disco, uptime
- list_cron_jobs -- trabajos programados y estado de última ejecución
- list_backups -- programaciones de respaldo e historial reciente
- list_databases -- instancias de base de datos y sus tamaños
Herramientas de acción (ejecutadas por el dashboard):
- restart_app -- reiniciar un contenedor por nombre de aplicación
Herramientas manejadas por el gateway (ejecutadas del lado del servidor, sin viaje de ida y vuelta al cliente):
- generate_config_file -- producir un sh0.yaml, docker-compose.yml o Dockerfile
- suggest_actions -- generar chips de acción de seguimiento para la interfaz
El protocolo de streaming SSE
El gateway usa Server-Sent Events para transmitir respuestas al dashboard. Extendimos los tipos de eventos SSE estándar para manejar llamadas a herramientas:
event: start
data: {"model":"claude-sonnet-4-6","conversation_id":"..."}
event: delta
data: {"text":"Déjame verificar el estado de tu servidor..."}
event: tool_call
data: {"id":"toolu_01...","name":"get_server_status","input":{}}
event: tool_call_done
data: {"tool_calls":[{"id":"toolu_01...","name":"get_server_status","input":{}}]}
event: usage
data: {"input_tokens":417,"output_tokens":53,"cost_cents":0.12}
event: done
data: {}El bucle agéntico: runStreamLoop
La pieza más interesante de código del lado del cliente es la función recursiva runStreamLoop en el store de IA. Maneja el ciclo completo de streaming, ejecución de herramientas y continuación. La profundidad de recursión está limitada a 10 iteraciones. En la práctica, la mayoría de consultas se completan en 1-3 iteraciones.
Ejecución de herramientas del lado del cliente
El dashboard mapea nombres de herramientas a llamadas API locales. El desafío clave es la resolución nombre-a-ID: Claude piensa en nombres de aplicaciones ("my-api"), pero la API REST de sh0 usa UUIDs. Mantenemos un caché de 30 segundos de mapeos nombre-a-ID de aplicaciones. Los resultados se truncan a 4.000 caracteres para gestionar el uso de la ventana de contexto.
El system prompt: Convirtiendo a Claude en un ingeniero DevOps
El system prompt es la pieza de ingeniería más cuidadosamente elaborada de todo el sistema. Está estructurado como secciones XML y se construye dinámicamente con contexto del servidor. La sección <tool-policy> es crítica. Sin ella, Claude a veces adivinaba el estado del servidor basándose en conocimiento general en lugar de llamar a la herramienta. La instrucción explícita "Nunca fabrique datos del servidor. Si no puede recuperarlos, dígalo" eliminó esta clase de alucinación.
La interfaz de chat: Se siente como en casa
La interfaz de chat sigue patrones que los usuarios ya conocen de ChatGPT y Claude.ai, adaptados para un contexto DevOps:
- Selector de modelo: tres botones píldora -- Haiku (verde, rápido, económico), Sonnet (azul, equilibrado), Opus (púrpura, potente)
- Barra lateral de conversaciones: agrupadas por fecha con acciones de favorito, archivo, renombrar y eliminar. Todo persistido en localStorage
- Estado de bienvenida: botones de acción rápida para tareas comunes
- Pie de monedero: saldo restante y mensajes estimados a la tarifa de Haiku
Todo el historial de conversaciones vive en localStorage. Deliberadamente evitamos el almacenamiento del lado del servidor para conversaciones del dashboard -- las consultas de infraestructura del usuario deberían permanecer en su máquina.
Lo que aprendimos
Construir un AI gateway nos enseñó tres cosas:
- La ejecución del lado del cliente es la arquitectura correcta para herramientas de infraestructura. Enrutar datos del servidor a través de un gateway central sería una pesadilla de seguridad y privacidad.
- El bucle agéntico necesita un límite duro. Sin el límite de 10 iteraciones, un Claude confundido podría repetir indefinidamente, quemando créditos y sin producir nada útil.
- El system prompt es el producto. La diferencia entre "Claude con herramientas sh0" y "un ingeniero DevOps que resulta ser IA" está completamente en el prompt.
Siguiente en la serie: Construyendo un servidor MCP: 25 herramientas, seguridad de 3 niveles, impulsado por OpenAPI -- cómo expandimos de 10 herramientas del gateway a 25 herramientas MCP con claves API con alcance, tokens de confirmación y generación impulsada por OpenAPI.