Raymon

Raymon is a local-first Ray-style log receiver with an HTTP ingest endpoint, a Streamable HTTP MCP server, durable JSONL storage, and a Ratatui terminal UI.

Use Raymon when you want Ray-compatible dumps from your app to be visible in a terminal and searchable by AI agents through MCP.

Raymon listens on the Ray default port,23517, so many Ray client libraries can target it with little or no configuration.

- A Raymon binary from Cargo, Homebrew, GitHub Releases, or a local source build.
- A terminal. The default run mode opens the TUI.

Expected result: the TUI opens and demo events begin appearing. Press?for help orqto stop Raymon.

Send a Ray-style event from another 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" } }'

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

Download a prebuilt archive fromGitHub Releases, extract it, and placeraymonon yourPATH.

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

Known Ray integrations include PHP, JavaScript, Bash, Ruby, Python, Go, Dart, and Rust. For Rust-native payloads, seeray-dbg.

Inbound envelopes must include a non-emptyuuid, at least one payload, a non-emptypayloads[].type, and a non-emptypayloads[].origin.hostname. When the same UUID is ingested more than once, Raymon merges the payloads into one entry and stores the merged entry before it publishes live state or events.

This starts the HTTP ingest endpoint, the MCP endpoint, and the TUI on127.0.0.1:23517.

Use this for background logging, MCP-only workflows, or tests.

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

Raymon refuses non-loopback binds unlessRAYMON_ALLOW_REMOTE=1is set. If the bind address is non-loopback, Raymon also requiresRAYMON_AUTH_TOKENunless you explicitly setRAYMON_ALLOW_INSECURE_REMOTE=1.
- Defaults.
- ray.json.
- Environment variables.
- CLI flags.

Raymon searches forray.jsonfrom the current directory upward. If it finds one, the directory containing that file becomes the storage root. Withoutray.json, the current working directory is the storage root.

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

Environment variables use the same concepts withRAYMON_names:

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

Each color can be#RRGGBB,rgb:RR/GG/BB, orrgb:RRRR/GGGG/BBBB.

Raymon stores entries as newline-delimited JSON in:

Thedata/directory is created under the active storage root. The TUI also writes session archives under:

On startup, Raymon restores stored entries into the core state so MCP search can see persisted logs. The TUI starts with a fresh live view and lets you browse archive files from the archives pane.

Retention keeps the newest distinct UUIDs. During restore, Raymon skips corrupt JSONL lines and legacy blob entries instead of aborting startup.

POST /also accepts MCP JSON-RPC requests as a compatibility fallback when ingest parsing rejects the body and the JSON looks like MCP JSON-RPC. Prefer/mcpfor new MCP clients.

WhenRAYMON_AUTH_TOKENis set, every request must include one of these headers:

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

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

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

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

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

Search stored entries and return compact summaries.

{ "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)" }

typesandcolorsalso accept comma-separated strings:

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

{ "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 }

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

{ "uuid": "<uuid>" }

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

{ "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 } } ] } ] }

Connected MCP peers receiveray/eventnotifications for inserted, updated, cleared, and lagged events. If a client receives a lag notification, it should refresh withraymon.search.

The TUI is keyboard-first and has built-in help. Press?for the full keymap.

Mouse support is enabled: click to focus or select, and use the wheel to move through the pane under the pointer.

Raymon uses the terminal ANSI palette by default, so it inherits light, dark, and base16-style terminal themes. UseRAYMON_TUI_PALETTEwhen you need a fixed palette.

This repository includes an AI-facing runbook atskills/raymon/SKILL.md. It teaches agents how to:

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

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

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

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

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB