Raymon

Ingesta HTTP con estado + servidor MCP + interfaz de terminal para registros estilo Ray.

Documentación

raymon

Raymon es un receptor de logs estilo Ray, local-first, con un endpoint HTTP de ingesta, un servidor MCP Streamable HTTP, almacenamiento JSONL duradero y una interfaz de terminal Ratatui.

Usa Raymon cuando quieras que los volcados compatibles con Ray de tu aplicación sean visibles en una terminal y buscables por agentes de IA a través de MCP.

Qué ofrece Raymon

Superficie	Qué hace
Ingesta HTTP	Acepta sobres JSON estilo Ray en `POST /`.
Servidor MCP	Expone `raymon.search` y `raymon.get_entries` en `POST /mcp`.
Interfaz de terminal	Navega por logs en vivo, filtra por pantalla/tipo/color, abre cargas útiles, copia detalles y gestiona archivos JSONL.
Almacenamiento	Persiste entradas en `data/entries.jsonl` bajo la raíz de almacenamiento activa.
API de crate Rust	Expone `raymon::run()` más los módulos públicos `raymon_core`, `raymon_ingest`, `raymon_storage`, `raymon_mcp` y `raymon_tui` para integración y pruebas.

Raymon escucha en el puerto predeterminado de Ray, 23517, por lo que muchas bibliotecas cliente de Ray pueden apuntar a él con poca o ninguna configuración.

Inicio rápido

Requisitos previos

Un binario de Raymon desde Cargo, Homebrew, GitHub Releases o una compilación local desde el código fuente.
Una terminal. El modo de ejecución predeterminado abre la TUI.

Ejecutar con eventos generados

Inicia Raymon en modo demo:

raymon --demo

Resultado esperado: la TUI se abre y los eventos demo comienzan a aparecer. Presiona ? para obtener ayuda o q para detener Raymon.

Ejecutar sin la TUI y enviar un evento

Inicia Raymon en una terminal:

RAYMON_NO_TUI=1 raymon

Envía un evento estilo Ray desde otra terminal:

curl -sS http://127.0.0.1:23517/ \
  -H 'content-type: application/json' \
  -d '{
    "uuid": "readme-demo-1",
    "payloads": [
      {
        "type": "log",
        "content": {
          "message": "hello from Raymon",
          "color": "green"
        },
        "origin": {
          "hostname": "local",
          "fileName": "README.md",
          "lineNumber": 1
        }
      }
    ],
    "meta": {
      "project": "raymon-readme",
      "host": "local",
      "screen": "readme"
    }
  }'

La salida esperada contiene:

{"ok":true,"error":null}

Detén el servidor con Ctrl+C.

Instalación

Cargo

Raymon requiere Rust 1.89 o más reciente.

cargo install raymon

Homebrew

brew install bnomei/raymon/raymon

GitHub Releases

Descarga un archivo precompilado desde GitHub Releases, extráelo y coloca raymon en tu PATH.

Desde el código fuente

git clone https://github.com/bnomei/raymon.git
cd raymon
cargo build --release

El binario se escribe en target/release/raymon.

Envío de logs

Raymon almacena entradas de log estilo Ray. Genéralas con una biblioteca compatible con Ray en tu aplicación y luego apunta esa biblioteca al host y puerto de Raymon.

Las integraciones conocidas de Ray incluyen PHP, JavaScript, Bash, Ruby, Python, Go, Dart y Rust. Para cargas útiles nativas de Rust, consulta ray-dbg.

El endpoint local predeterminado es:

http://127.0.0.1:23517/

Si tu remitente usa los valores predeterminados de escritorio de Ray, Raymon generalmente funciona iniciando raymon antes de emitir logs.

Los sobres entrantes deben incluir un uuid no vacío, al menos una carga útil, un payloads[*].type no vacío y un payloads[*].origin.hostname no vacío. Cuando el mismo UUID se ingiere más de una vez, Raymon fusiona las cargas útiles en una sola entrada y almacena la entrada fusionada antes de publicar el estado en vivo o los eventos.

Modos de ejecución

TUI local

raymon

Esto inicia el endpoint HTTP de ingesta, el endpoint MCP y la TUI en 127.0.0.1:23517.

Servidor local sin interfaz

RAYMON_NO_TUI=1 raymon

Úsalo para registro en segundo plano, flujos de trabajo solo MCP o pruebas.

Servidor remoto con autenticación

export RAYMON_AUTH_TOKEN="change-me"
RAYMON_ALLOW_REMOTE=1 \
RAYMON_HOST=0.0.0.0 \
RAYMON_NO_TUI=1 \
raymon

Raymon rechaza enlaces que no sean de bucle local a menos que RAYMON_ALLOW_REMOTE=1 esté configurado. Si la dirección de enlace no es de bucle local, Raymon también requiere RAYMON_AUTH_TOKEN a menos que establezcas explícitamente RAYMON_ALLOW_INSECURE_REMOTE=1.

Referencia de CLI

raymon [OPTIONS]

Opción	Significado
`--host <HOST>`	Sobrescribir el host de enlace HTTP.
`--port <PORT>`	Sobrescribir el puerto de enlace HTTP.
`--config <PATH>`	Cargar un archivo de configuración JSON específico en lugar de buscar `ray.json`.
`--ide <COMMAND>`	Comando usado por la TUI para abrir archivos de origen.
`--editor <COMMAND>`	Comando usado por la TUI para abrir cargas útiles de detalle seleccionadas en un archivo temporal.
`--jq <COMMAND>`	Comando `jq` usado para búsquedas en el panel de detalle.
`--tui`	Habilitar la TUI.
`--no-tui`	Deshabilitar la TUI.
`--demo`	Generar eventos demo locales.
`-v`, `--verbose`	Habilitar registro de información. Usa `-vv` para registro de depuración.
`-h`, `--help`	Imprimir ayuda de CLI.
`-V`, `--version`	Imprimir la versión de Raymon.

La precedencia de configuración es:

Valores predeterminados.
ray.json.
Variables de entorno.
Banderas de CLI.

Configuración

Raymon busca ray.json desde el directorio actual hacia arriba. Si encuentra uno, el directorio que contiene ese archivo se convierte en la raíz de almacenamiento. Sin ray.json, el directorio de trabajo actual es la raíz de almacenamiento.

Ejemplo de ray.json:

{
  "host": "127.0.0.1",
  "port": 23517,
  "tui": true,
  "max_entries": 10000,
  "storage_max_entries": 100000,
  "mcp_redact_payloads": false
}

Las variables de entorno usan los mismos conceptos con nombres RAYMON_:

Variable	Predeterminado	Significado
`RAYMON_ENABLED`	`true`	Habilitar o deshabilitar Raymon.
`RAYMON_HOST`	`127.0.0.1`	Dirección de enlace HTTP.
`RAYMON_PORT`	`23517`	Puerto de enlace HTTP.
`RAYMON_TUI`	`true`	Habilitar la TUI.
`RAYMON_NO_TUI`	`false`	Deshabilitar la TUI. Tiene prioridad sobre `RAYMON_TUI`.
`RAYMON_IDE`	`code`	Comando de IDE usado para saltos de archivo de origen. Para saltos de línea de VS Code, usa `code --goto`.
`RAYMON_EDITOR`	`VISUAL`/`EDITOR`/`vim`	Comando de editor usado para cargas útiles de detalle seleccionadas.
`RAYMON_JQ`	`jq`	Comando `jq` usado para búsqueda de detalle.
`RAYMON_MAX_BODY_BYTES`	`1048576`	Tamaño máximo del cuerpo de solicitud HTTP y del tamaño de entrada fusionada almacenada.
`RAYMON_MAX_QUERY_LEN`	`265`	Longitud máxima de búsqueda, comando, selector y consulta MCP en bytes.
`RAYMON_MAX_ENTRIES`	`10000`	Máximo de entradas mantenidas en memoria para MCP y resincronización en vivo. `0` deshabilita la expulsión en memoria.
`RAYMON_STORAGE_MAX_ENTRIES`	`100000`	Máximo de entradas distintas mantenidas en `data/entries.jsonl`. `0` deshabilita la retención de almacenamiento.
`RAYMON_JQ_TIMEOUT_MS`	`10000`	Tiempo de espera de búsqueda de detalle `jq` en milisegundos.
`RAYMON_ALLOW_REMOTE`	`false`	Permitir enlace a direcciones que no sean de bucle local.
`RAYMON_ALLOW_INSECURE_REMOTE`	`false`	Permitir enlace sin bucle local sin autenticación. Evita esto a menos que aceptes el riesgo de exposición.
`RAYMON_INSECURE_REMOTE`	sin configurar	Alias para `RAYMON_ALLOW_INSECURE_REMOTE`.
`RAYMON_ALLOW_MCP_SHUTDOWN`	`false`	Permitir que los métodos personalizados MCP `ray/quit`, `ray/exit`, `raymon/quit` y `raymon/exit` detengan Raymon.
`RAYMON_MCP_REDACT_PAYLOADS`	`false`	Redactar campos de carga útil de apariencia sensible en resultados MCP y notificaciones de eventos.
`RAYMON_AUTH_TOKEN`	sin configurar	Requerir `Authorization: Bearer <token>` o `x-raymon-token: <token>` para todas las solicitudes HTTP.
`RAYMON_TOKEN`	sin configurar	Alias para `RAYMON_AUTH_TOKEN`.
`RAYMON_TUI_PALETTE`	sin configurar	Sobrescribir la paleta de la TUI con 18 colores separados por comas.
`RAYMON_PALETTE`	sin configurar	Alias para `RAYMON_TUI_PALETTE`.
`RAYMON_LOG`	sin configurar	Filtro de rastreo. Se usa `RUST_LOG` cuando no está configurado.

RAYMON_TUI_PALETTE espera:

fg,bg,black,red,green,yellow,blue,magenta,cyan,white,bright_black,bright_red,bright_green,bright_yellow,bright_blue,bright_magenta,bright_cyan,bright_white

Cada color puede ser #RRGGBB, rgb:RR/GG/BB o rgb:RRRR/GGGG/BBBB.

Almacenamiento

Raymon almacena entradas como JSON delimitado por nuevas líneas en:

data/entries.jsonl

El directorio data/ se crea bajo la raíz de almacenamiento activa. La TUI también escribe archivos de sesión bajo:

data/archives/

Al iniciar, Raymon restaura las entradas almacenadas en el estado central para que la búsqueda MCP pueda ver los logs persistidos. La TUI comienza con una vista en vivo nueva y te permite navegar por los archivos de archivo desde el panel de archivos.

La retención mantiene los UUIDs distintos más recientes. Durante la restauración, Raymon omite líneas JSONL corruptas y entradas de blob heredadas en lugar de abortar el inicio.

API HTTP

Método y ruta	Propósito
`POST /`	Endpoint de ingesta de Ray para sobres de carga útil de Ray.
`POST /mcp`	Endpoint MCP Streamable HTTP. Prefiere esta ruta para clientes MCP.

POST / también acepta solicitudes JSON-RPC de MCP como respaldo de compatibilidad cuando el análisis de ingesta rechaza el cuerpo y el JSON parece JSON-RPC de MCP. Prefiere /mcp para nuevos clientes MCP.

Cuando RAYMON_AUTH_TOKEN está configurado, cada solicitud debe incluir uno de estos encabezados:

Authorization: Bearer <token>
x-raymon-token: <token>

Las respuestas de ingesta usan códigos de estado HTTP:

Estado	Significado
`200`	El sobre se almacenó y publicó.
`400`	El cuerpo de la solicitud era JSON inválido.
`413`	La entrada fusionada excedió `RAYMON_MAX_BODY_BYTES`.
`422`	Al sobre le faltaban campos requeridos o tenía datos inválidos.
`500`	Falló el manejo de almacenamiento, estado o bus de eventos.

Configuración de MCP

Agrega un servidor MCP local de Raymon a Codex:

codex mcp add raymon --url http://127.0.0.1:23517/mcp

Configuración remota con autenticación de token portador:

codex mcp add raymon \
  --url http://<host>:23517/mcp \
  --bearer-token-env-var RAYMON_AUTH_TOKEN

JSON MCP equivalente:

{
  "mcpServers": {
    "raymon": {
      "url": "http://127.0.0.1:23517/mcp"
    }
  }
}

JSON MCP remoto con autenticación:

{
  "mcpServers": {
    "raymon": {
      "url": "http://<host>:23517/mcp",
      "headers": {
        "Authorization": "Bearer ${RAYMON_AUTH_TOKEN}"
      }
    }
  }
}

Herramientas MCP

Raymon expone dos herramientas de solo lectura.

`raymon.search`

Busca entradas almacenadas y devuelve resúmenes compactos.

Entrada:

{
  "query": "string (optional; plain text or /regex/)",
  "types": ["string"],
  "colors": ["string"],
  "screen": "string (optional)",
  "project": "string (optional)",
  "host": "string (optional)",
  "limit": "number (optional)",
  "offset": "number (optional)"
}

types y colors también aceptan cadenas separadas por comas:

{ "types": "error,exception", "colors": "red" }

Resultado:

{
  "entries": [
    {
      "uuid": "string",
      "received_at": 0,
      "project": "string",
      "host": "string",
      "screen": "string",
      "payload_count": 1,
      "payload_types": ["log"]
    }
  ],
  "count": 1,
  "limit": 100,
  "offset": 0,
  "scan_limit": 5000
}

Valores predeterminados y límites:

Campo	Predeterminado	Límite
`limit`	`100`	`500`
`offset`	`0`	`5000`
`scan_limit`	`5000`	Ventana fija de escaneo de entradas más recientes
`query`	sin configurar	`RAYMON_MAX_QUERY_LEN` bytes

`raymon.get_entries`

Obtiene entradas completas por UUID.

Entrada:

{
  "uuids": ["<uuid>"],
  "redact": false
}

Alias de entrada admitidos:

{ "uuid": "<uuid>" }

{ "uuids": "<uuid-1>,<uuid-2>" }

redacted y redact_payloads son alias para redact. Cuando la redacción está habilitada, Raymon reemplaza campos de carga útil de apariencia sensible como contraseñas, tokens, claves de API, cookies y secretos.

Resultado:

{
  "entries": [
    {
      "uuid": "string",
      "received_at": 0,
      "project": "string",
      "host": "string",
      "screen": "string",
      "session_id": null,
      "payloads": [
        {
          "type": "log",
          "content": {},
          "origin": {
            "project": "string",
            "host": "string",
            "screen": "string",
            "session_id": null,
            "function_name": null,
            "file": null,
            "line_number": null
          }
        }
      ]
    }
  ]
}

Límites:

Límite	Valor
UUIDs por solicitud	`100`
Bytes por UUID	`265`
Resultado de herramienta serializado	`1048576` bytes

Los pares MCP conectados reciben notificaciones ray/event para eventos insertados, actualizados, borrados y con retraso. Si un cliente recibe una notificación de retraso, debe actualizarse con raymon.search.

TUI

La TUI está orientada al teclado y tiene ayuda integrada. Presiona ? para el mapa de teclas completo.

Clave	Acción
`?`	Abrir los atajos de teclado.
`q`	Salir de Raymon y detener el servidor HTTP/MCP.
`Space`	Abrir el menú de selección.
`/` o `f`	Buscar mensajes y rutas de archivos con búsqueda difusa.
`r`	Iniciar una búsqueda con expresiones regulares.
`:`	Buscar dentro del payload de detalle seleccionado. Usa `jq` para consultas JSON cuando esté disponible.
`j`/`k`, flechas	Moverse en el panel enfocado.
`h`/`l`, flechas izquierda/derecha	Mover el foco a la izquierda o a la derecha.
`J`/`K`, `PageUp`/`PageDown`	Desplazarse por el panel de detalle.
`Tab`, `Shift+Tab`	Mover el foco entre registros, detalle y archivos.
`g`	Ir a una posición de registro.
`G`	Saltar al último registro.
`s`	Ajustar los filtros de color y tipo a la entrada de registro seleccionada.
`u`	Restablecer búsqueda y filtros.
`p`	Pausar o reanudar las actualizaciones en vivo.
`a`	Alternar el panel de archivos.
`x`	Archivar la vista actual en un archivo JSONL.
`Enter`	Cargar el archivo seleccionado cuando el panel de archivos tenga el foco.
`n`	Renombrar el archivo seleccionado. Los archivos en vivo no se pueden renombrar.
`d`	Eliminar el archivo seleccionado tras la confirmación. Los archivos en vivo no se pueden eliminar.
`y`	Copiar la entrada de lista seleccionada.
`Y`	Copiar el payload de detalle seleccionado.
`z`	Alternar la representación JSON expandida.
`Z`	Alternar la representación JSON sin procesar.
`m`	Alternar los payloads de estilo y metadatos en el panel de detalle.
`1` hasta `6`	Alternar columnas de lista: punto de color, marca de tiempo, etiqueta de tipo, archivo, mensaje, UUID.
`o`	Abrir el archivo de origen en el IDE configurado.
`e`	Abrir el payload de detalle seleccionado en el editor configurado.
`Ctrl+l`	Limpiar la lista de registros en vivo sin eliminar las entradas almacenadas.
`Ctrl+c`	Salir desde cualquier lugar.

El soporte de ratón está habilitado: haz clic para enfocar o seleccionar, y usa la rueda para desplazarte por el panel bajo el puntero.

Raymon usa la paleta ANSI del terminal por defecto, por lo que hereda los temas de terminal claros, oscuros y estilo base16. Usa RAYMON_TUI_PALETTE cuando necesites una paleta fija.

Habilidad del agente

Este repositorio incluye un manual orientado a IA en skills/raymon/SKILL.md. Enseña a los agentes cómo:

Generar eventos estilo Ray con integraciones comunes de Ray.
Añadir Raymon como servidor MCP local o remoto.
Usar raymon.search antes de raymon.get_entries para inspeccionar registros de manera eficiente.

La habilidad es documentación para agentes. No es código de ejecución.

Estructura del código fuente

Ruta	Propósito
`src/cli.rs`	Ciclo de vida del runtime, configuración, restauración de almacenamiento, modo demo y orquestación TUI/servidor.
`src/cli/http.rs`	Router Axum, autenticación, límites de cuerpo, límites de concurrencia, ingesta y montaje MCP.
`src/raymon_core.rs`	Tipos de dominio sin E/S, filtros, eventos y normalización de envolturas Ray.
`src/raymon_ingest.rs`	Análisis de ingesta HTTP, validación, fusión de UUID duplicados, almacenamiento y emisión de eventos.
`src/raymon_mcp.rs`	Herramientas MCP, notificaciones, límites de consulta, límites de resultados y enlaces de apagado.
`src/raymon_mcp/schema.rs`	Esquemas de solicitud y respuesta MCP.
`src/raymon_storage/`	Persistencia JSONL, indexación, listado y retención.
`src/raymon_tui.rs`	Estado TUI, renderizado, búsqueda, filtrado, manejo de teclas, integración con editor y flujos de archivo.
`tests/ray_php_local.rs`	Prueba de integración PHP/Ray local ignorada.

Desarrollo

Ejecuta la suite de pruebas de Rust:

cargo test --all-targets

Ejecuta las comprobaciones de formato y clippy:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Ejecuta los hooks de pre-commit cuando prek esté instalado:

prek validate-config prek.toml
prek run --all-files
prek install

Ejecuta la prueba de integración PHP Ray solo local después de instalar el helper global de PHP ray():

cargo test --test ray_php_local -- --ignored ray_php_local_integration

Compila y empaqueta los artefactos de lanzamiento:

TARGET=x86_64-apple-darwin scripts/build-release.sh
VERSION=0.7.0 TARGET=x86_64-apple-darwin scripts/package-release.sh

El flujo de lanzamiento compila objetivos Linux musl (x86_64, aarch64), macOS (x86_64, aarch64) y Windows MSVC (x86_64). Los artefactos Unix son archivos .tar.gz, los artefactos Windows son archivos .zip, y cada paquete recibe un archivo .sha256.

Licencia

MIT. Ver LICENSE.