接入你的智能体
從發布者安裝。不是 PlugMCP 端點。
遠端 URL 還是本機指令? 兩種安裝方式的差異
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.
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.
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.
Raymon requires Rust 1.89 or newer.
cargo install raymon
brew install bnomei/raymon/raymon
Download a prebuilt archive from GitHub Releases, extract it, and place raymon on your PATH.
git clone https://github.com/bnomei/raymon.git
cd raymon
cargo build --release
The binary is written to target/release/raymon.
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.
raymon
This starts the HTTP ingest endpoint, the MCP endpoint, and the TUI on 127.0.0.1:23517.
RAYMON_NO_TUI=1 raymon
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 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.
raymon [OPTIONS]
Configuration precedence is:
ray.json.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.
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.
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:
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}"
}
}
}
}
Raymon exposes two read-only tools.
raymon.searchSearch 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_entriesFetch 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.
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.
This repository includes an AI-facing runbook at skills/raymon/SKILL.md. It teaches agents how to:
raymon.search before raymon.get_entries to inspect logs efficiently.The skill is documentation for agents. It is not runtime code.
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.
MIT. See LICENSE.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
這筆記錄未列出必要的環境變數。
Raymon 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Ray logging TUI and MCP Server