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.

What Raymon provides

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

Sending logs

Raymon stores Ray-style log entries. Generate them with a Ray-compatible library in your application, then point that library at Raymon's host and port.

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

The default local endpoint is:

http://127.0.0.1:23517/

If your sender uses the Ray desktop defaults, Raymon usually works by starting raymon before you emit logs.

Inbound envelopes must include a non-empty uuid, at least one payload, a non-empty payloads[*].type, and a non-empty payloads[*].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.

Run modes

Local TUI

raymon

This starts the HTTP ingest endpoint, the MCP endpoint, and the TUI on 127.0.0.1:23517.

Headless local server

RAYMON_NO_TUI=1 raymon

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

Remote server with auth

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 unless RAYMON_ALLOW_REMOTE=1 is set. If the bind address is non-loopback, Raymon also requires RAYMON_AUTH_TOKEN unless you explicitly set RAYMON_ALLOW_INSECURE_REMOTE=1.

CLI reference

raymon [OPTIONS]

Configuration precedence is:

1. Defaults.
2. ray.json.
3. Environment variables.
4. CLI flags.

Storage

Raymon stores entries as newline-delimited JSON in:

data/entries.jsonl

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

data/archives/

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.

HTTP API

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 /mcp for new MCP clients.

When RAYMON_AUTH_TOKEN is set, every request must include one of these headers:

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

Ingest responses use HTTP status codes:

MCP tools

Raymon exposes two read-only tools.

raymon.search

Search stored entries and return compact summaries.

Input:

{
  "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 and colors also accept comma-separated strings:

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

Result:

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

Defaults and limits:

raymon.get_entries

Fetch full entries by UUID.

Input:

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

Supported input aliases:

{ "uuid": "<uuid>" }

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

redacted and redact_payloads are aliases for redact. When redaction is enabled, Raymon replaces sensitive-looking payload fields such as passwords, tokens, API keys, cookies, and secrets.

Result:

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

Limits:

Connected MCP peers receive ray/event notifications for inserted, updated, cleared, and lagged events. If a client receives a lag notification, it should refresh with raymon.search.

TUI

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. Use RAYMON_TUI_PALETTE when you need a fixed palette.

Agent skill

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

• Generate Ray-style events with common Ray integrations.
• Add Raymon as a local or remote MCP server.
• Use raymon.search before raymon.get_entries to inspect logs efficiently.

The skill is documentation for agents. It is not runtime code.

Source layout

Development

Run the Rust test suite:

cargo test --all-targets

Run formatting and clippy checks:

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

Run pre-commit hooks when prek is installed:

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

Run the local-only PHP Ray integration test after installing the global PHP ray() helper:

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

Build and package release artifacts:

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

The release workflow builds Linux musl (x86_64, aarch64), macOS (x86_64, aarch64), and Windows MSVC (x86_64) targets. Unix artifacts are .tar.gz archives, Windows artifacts are .zip archives, and each package gets a .sha256 file.

Quickstart

Prerequisites

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

Run with generated events

Start Raymon in demo mode:

raymon --demo

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

Run without the TUI and send one event

Start Raymon in one terminal:

RAYMON_NO_TUI=1 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"
    }
  }'

Expected output contains:

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

Stop the server with Ctrl+C.

Installation

Cargo

Raymon requires Rust 1.89 or newer.

cargo install raymon

Homebrew

brew install bnomei/raymon/raymon

GitHub Releases

Download a prebuilt archive from GitHub Releases, extract it, and place raymon on your PATH.

From source

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

The binary is written to target/release/raymon.

Configuration

Raymon searches for ray.json from the current directory upward. If it finds one, the directory containing that file becomes the storage root. Without ray.json, the current working directory is the storage root.

Example ray.json:

{
  "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 with RAYMON_ names:

RAYMON_TUI_PALETTE expects:

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, or rgb:RRRR/GGGG/BBBB.

MCP setup

Add a local Raymon MCP server to Codex:

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

Remote setup with bearer-token auth:

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

Equivalent MCP JSON:

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

Remote MCP JSON with auth:

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

License

MIT. See LICENSE.