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.

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`.

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.

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`.

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 
x-raymon-token:

Ingest responses use HTTP status codes:

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://: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://:23517/mcp",
      "headers": {
        "Authorization": "Bearer ${RAYMON_AUTH_TOKEN}"
      }
    }
  }
}

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": [""],
  "redact": false
}

Supported input aliases:

{ "uuid": "" }

{ "uuids": "," }

`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.

License

MIT. See `LICENSE`.