HarnessRouter interfaz unificada agentes IA: el repositorio HarnessRouter/harnessrouter ofrece una capa autoalojable que controla varios arneses de agentes (Codex, Claude Code, Hermes y una treintena más) tras una sola API. Tiene unas 3 700 estrellas y 395 forks a finales de octubre de 2026, con licencia Apache 2.0. Es un repositorio joven: la página de releases muestra una decena de versiones 0.36 y 0.37 publicadas entre el 23 y el 27 de octubre de 2026, entre ellas la v0.37.6 del 27 de octubre.
Para un SRE el interés es sencillo: un único punto de entrada para lanzar, seguir y cancelar tareas de agentes, en lugar de una integración por herramienta. La siguiente pregunta llega enseguida: ¿qué se puede observar desde ese punto? Este artículo sigue el README, la guía de autoalojamiento y el archivo LICENSE, leídos el 27 de octubre de 2026.
Precisión de honestidad: span.observer no ha instalado HarnessRouter. Los comandos proceden del README y las tres capturas son imágenes publicadas en la carpeta docs/images del repositorio, bajo su licencia Apache 2.0.
HarnessRouter interfaz unificada agentes IA: qué dice el repositorio
- Función: el README lo describe como «la interfaz unificada para arneses de agentes». Aquí un arnés es un agente de línea de comandos como Codex o Claude Code. HarnessRouter los expone mediante una API compatible con la OpenAI Responses API, con sesiones persistentes, flujo de progreso, archivos, cancelación y errores estructurados.
- Protocolo: implementa el Unified Harness Protocol (UHP). El repositorio contiene la implementación de referencia, los esquemas y una suite de conformidad.
- Licencia: Apache 2.0 (archivo LICENSE leído, con un NOTICE de dependencias). Los CLI de agentes que se instalan en el primer arranque conservan sus propias licencias: la guía cita, por ejemplo, las condiciones de Anthropic para Claude Code y pide revisar la licencia de Hermes.
- Cifras: unas 3 700 estrellas, 395 forks y 789 commits en la rama principal, leídos en la página del repositorio. La página no muestra el desglose de lenguajes, así que no citamos ninguno.
- Alcance: unas 30 bases de agentes listadas (Codex, Claude Code, Hermes, Pi, OpenCode, Gemini CLI, Cline, goose, Aider, OpenHands y más). Una matriz de soporte indica cuáles funcionan con cada proveedor.
Visita a la interfaz
La consola web escucha en el puerto 3000. El README describe tres pasos: conectar una clave de proveedor de modelos («Bring your own key»), describir en una frase lo que debe hacer el agente y enviar una primera tarea.

Según el README, HarnessRouter escribe entonces las instrucciones del agente, elige el arnés, el modelo, las habilidades y las herramientas, y deja una petición de ejemplo. El arnés queda fijado al guardar la configuración: para cambiarlo, se crea otra.

El README ofrece también tres ejemplos cuya petición reproduce una ejecución grabada, para ver una tarea terminada sin gastar tokens. La siguiente captura muestra uno: un archivo producido, la etiqueta «Recorded» y una duración de 105,2 segundos.

Instalación paso a paso
Requisitos según el README: Docker, unos 4 GB de disco y una clave API de un proveedor de modelos. No hace falta cuenta de HarnessRouter y no se incluye ningún modelo ni clave de prueba. El README no detalla un procedimiento por sistema: todo pasa por Docker.
Paso 1 — Lanzar el contenedor
docker run -d --name harnessrouter \
-p 127.0.0.1:3000:3000 \
-v harnessrouter:/data \
harnessrouter/harnessrouter
El volumen con nombre conserva la base de datos, los archivos, los CLI de agentes instalados y los espacios de trabajo. No añadas --user: el punto de entrada necesita root para gestionar un usuario por sesión. Mantén el enlace a 127.0.0.1 mientras no cambies la contraseña inicial.
Paso 2 — Esperar al final del primer arranque
docker logs -f harnessrouter
El primer arranque instala los CLI de agentes. Continúa cuando el registro muestre [harnessrouter] ready on :3000. La línea backends available: lista lo que se instaló de verdad.
Paso 3 — Abrir la consola y cambiar la contraseña
Abre http://localhost:3000. Las credenciales iniciales del README son harnessrouter tanto para el usuario como para la contraseña. Cámbialas en Profile antes de exponer nada; el registro repite una advertencia mientras siga la contraseña por defecto.
Paso 4 — Llamar a la API desde tu producto
Crea una clave en API Keys y guárdala en el servidor, en HARNESSROUTER_API_KEY. El arnés se elige con metadata.harness_id:
export HARNESSROUTER_BASE_URL=http://localhost:3000/api/harness
curl --fail-with-body -sS "$HARNESSROUTER_BASE_URL/v1/responses" \
-H "Authorization: Bearer ${HARNESSROUTER_API_KEY:?}" \
-H 'content-type: application/json' \
-d '{
"input":"Reply with exactly: it works.",
"metadata":{"harness_id":"codex"},
"model":"gpt-5.4-mini",
"stream":false
}'
Cambiar de agente es cambiar harness_id (y el modelo). Eso es el enrutado: la misma llamada, otro arnés. La tarea y su transcripción aparecen en la consola. Para reintentar una petición sin ejecutarla dos veces, envía la misma cabecera Idempotency-Key; una clave reutilizada con otro cuerpo devuelve un error 409.
Observar HarnessRouter: registros, tokens y trazas
Esto es lo que describe la documentación del repositorio, y nada más.
- Registros del contenedor:
docker logs -f harnessroutermuestra la instalación de los arneses, la líneaready on :3000, los arneses disponibles y las instalaciones fallidas. La guía indica que el registro nombra la instalación que falló. - Tokens por tarea: la respuesta de la API contiene un objeto
usageconinput_tokens,output_tokensytotal_tokens; la guía muestra tambiénreasoning_tokens, el recuento del proveedor, ausente cuando este no lo da. Son los campos que hay que recoger en el llamante para seguir el coste. - Contexto de traza W3C: si la petición lleva las cabeceras
traceparentytracestate, las llamadas al modelo de la tarea reciben un hijo de esa traza: mismo identificador de traza, nuevo identificador de span y la marca de muestreo conservada. Un valor no válido se descarta sin hacer fallar la tarea. La cabecerabaggagenunca se lee. - Historial de ejecución:
GET /v1/sessions/{session_id}/turnsdevuelve los turnos;GET /v1/traces/{session_id}/alldevuelve el flujo de eventos almacenado del arnés en JSON delimitado por saltos de línea, un evento por línea. - Datos de producto: la edición comunitaria desactiva la analítica de la consola.
Dos límites que conviene conocer. Primero, la guía indica que los spans de llamadas al proveedor (las peticiones al modelo detrás de un turno) pertenecen a la observabilidad del servicio alojado, no de esta edición. Segundo, en el README y la guía que leímos no encontramos exportación OTLP ni métricas Prometheus: las trazas se correlacionan en el llamante inyectando traceparent, y usage se recoge por cuenta propia. Para esa recogida, consulta el coste de un agente de IA en tokens con OpenTelemetry y observar agentes MCP con OpenTelemetry.
Límites y puntos abiertos
- Anclaje que señalar: repositorio muy reciente, con versiones publicadas casi a diario. Las frases del README («la primera interfaz unificada del mundo», un 99,8 % menos de coste y 3,2 veces más rápido en ocho configuraciones) son afirmaciones del proyecto. La metodología está en harnessrouter.ai/benchmarks, que no verificamos; el README aclara que lo más barato y lo más rápido varían según la tarea.
- Sin tope de coste: la guía dice que nada limita un turno por su coste; un arnés con
max_cost_usdse rechaza. Un turno se acota conmax_stepytimeout_seconds; los límites de gasto se fijan con el proveedor. - Seguridad: contraseña por defecto, un contenedor que necesita root, sesiones separadas por usuario del sistema y no por contenedor. El README advierte que un secreto legible por el agente puede enviarse a otro sitio si una instrucción se lo pide: dale tokens de corta duración y mínimos privilegios.
- Edición comunitaria: la facturación, los varios usuarios y las réplicas múltiples pertenecen al servicio alojado de pago. Los kits de inicio (Slides, Sheets, Dashboards, Videos, My Workplace) tienen condiciones distintas de las de la edición comunitaria.
- Licencias de origen: cada CLI de agente conserva su licencia; Apache 2.0 no las sustituye.
Para situar el proyecto, véanse OpenClaw (un agente y sus canales), Paperclip (orquestación de una flota), Orca (control de agentes de código), Ruflo (enjambres), ECC (optimización de arneses) y wshobson/agents (un mercado de plugins). En la serie, OpenBot cubre la misma necesidad en el escritorio. HarnessRouter se sitúa en el servidor, como pasarela de API.
Buenas prácticas
- Mantén
127.0.0.1y cambia la contraseña antes de publicar el puerto; pon el resto tras TLS, como describe la guía. - Limita los arneses instalados con
HR_BACKENDS: un arnés que no se instaló falla en su primera tarea. - Envía
traceparenten cada llamada para encontrar la tarea en tus trazas. - Registra
usagede cada respuesta y fija los topes de gasto con el proveedor. - Usa una
Idempotency-Keyen cada reintento. - Da a los agentes tokens de corta duración y mínimos privilegios.
Preguntas frecuentes
¿HarnessRouter es de código abierto?
La edición comunitaria tiene licencia Apache 2.0, según el archivo LICENSE. Los kits de inicio tienen condiciones distintas y los CLI de agentes conservan sus licencias originales.
¿HarnessRouter exporta trazas OpenTelemetry?
El README describe la propagación del contexto W3C (traceparent, tracestate) hacia las llamadas al modelo. La guía indica que los spans de llamadas al proveedor están reservados al servicio alojado. En las páginas leídas no se documenta ninguna exportación OTLP.
¿Cómo seguir el coste en tokens?
Lee el objeto usage de cada respuesta. Esta edición no tiene tope de coste: fíjalo con tu proveedor de modelos.
Conclusión
HarnessRouter ofrece un punto de entrada único para varios agentes de código, con enrutado por harness_id y una API ya familiar. La observabilidad queda por construir alrededor: registros del contenedor, usage y contexto de traza inyectado por el llamante. Pruébalo primero en local, sin exponer el puerto. Fuentes: repositorio HarnessRouter/harnessrouter y su guía de autoalojamiento.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC ni a los proyectos citados. Las marcas citadas pertenecen a sus propietarios. Las herramientas evolucionan rápido: comprueba los comandos y las opciones en su documentación oficial.