OTelux

A local-first OpenTelemetry workbench for developers and coding agents.
Receive, explore, and investigate traces, logs, and metrics without sending telemetry to a hosted backend.

Install · Features · Quick start · Docs · Security · Contributing

What you can do

• Inspect complete requests: navigate virtualized trace waterfalls and searchable span details, including attributes, resources, events, and links.
• Correlate every signal locally: search structured logs, explore metric series, and group telemetry by standard OpenTelemetry Source and Service identity.
• Give coding agents bounded evidence: query read-only traces, logs, service health, and agent-run correlation through the built-in MCP server.
• Keep ownership of telemetry: data stays in a retention-bounded local SQLite database; OTLP, MCP, and authenticated Runtime API listeners bind to loopback.

Install the Linux prerelease

OTelux is an open-source prerelease. Linux packages are available for early testing; interfaces and packaging may still change.

Download SHA256SUMS and one package from the v0.1.17 GitHub Release.

Install the x64 Debian/Ubuntu package:

grep '  OTelux-.*-amd64.deb$' SHA256SUMS | sha256sum -c -
sudo apt install ./OTelux-0.1.17-amd64.deb

Or run the rootless x64 AppImage:

grep '  OTelux-.*-x86_64.AppImage$' SHA256SUMS | sha256sum -c -
chmod +x OTelux-0.1.17-x86_64.AppImage
./OTelux-0.1.17-x86_64.AppImage

For Linux arm64, use OTelux-0.1.17-arm64.deb or OTelux-0.1.17-arm64.AppImage and the matching checksum line.

Platform	Package	Status
Linux x64	.deb, AppImage	Qualified prerelease
Linux arm64	.deb, AppImage	Qualified prerelease
macOS arm64/x64	DMG, ZIP	Unsigned preview; signing and notarization planned
Windows x64/arm64	—	Signed installer planned

Source setup is documented in Getting Started. OTelux does not recommend piping mutable network scripts into a privileged shell.

Product Ecosystem

The target product is one per-user OTelux runtime presented through four install and interaction forms: agent plugin, direct MCP integration, CLI, and Desktop. They share one receiver, engine, active SQLite database, query contract, and browser-safe UI. Installing another form later connects it to the same local data instead of creating another backend.

The browser workbench is not a separate product. The plugin and CLI open the shared workbench from the local runtime in a browser; Desktop embeds the same @otelux/ui application in its native shell.

Form	End-user experience	Availability
Agent plugin	Install in Claude or Codex to get OTelux skills, MCP tools, telemetry setup workflows, and a dashboard command.	Desktop-companion 0.1.5 exists; self-contained runtime is planned.
Direct MCP	Register OTelux as an MCP server without plugin skills or Electron.	Planned standalone packaging; current bridge connects to Desktop.
CLI	Run OTelux headlessly, inspect health and endpoints, manage settings, and open the browser workbench.	Private bundled oteluxctl lifecycle/status/config/doctor client live on main; browser open, SQLite quick-check, and public PATH distribution remain.
Desktop app	Use the native traces, logs, and metrics workbench with receiver and retention settings.	Pre-release app starts or reconnects to one on-demand packaged daemon; exiting Desktop leaves ingest running.

flowchart LR
  Sources[Applications and agent telemetry] -->|OTLP/HTTP| Runtime[One local OTelux runtime]
  Plugin[Agent plugin] --> Runtime
  MCP[Direct MCP] --> Runtime
  CLI[CLI] --> Runtime
  Desktop[Desktop] --> Runtime
  Runtime --> Engine[Shared receiver, engine, MCP, and UI API]
  Runtime --> Workbench[Shared workbench UI]
  Plugin -.->|open in browser| Workbench
  CLI -.->|open in browser| Workbench
  Desktop -.->|embed| Workbench
  Engine --> DB[(One active SQLite database)]

Loading

The runtime is the only process that opens SQLite, applies migrations and retention, and binds OTLP/MCP/Runtime API listeners. See docs/arch.md for lifecycle, migration, package boundaries, end-user scenarios, and the distinction between the current and target implementations.

Docs

• docs/spec.md — product, architecture, current state, package boundaries, and UX requirements.
• docs/plan.md — work ahead only.
• docs/release-sprint.md — finite public-release execution plan, launch gates, and evidence.
• docs/getting-started.md — current source setup, first telemetry, troubleshooting, and removal.
• docs/privacy.md — local data handling and safe telemetry sharing.
• docs/security-model.md — trust boundaries, current safeguards, and release blockers.
• docs/arch.md — the four product forms, shared local runtime, UI delivery, data ownership, and end-user scenarios.
• docs/agent-onboarding.md — CLI contract, safe multi-agent integration engine, Settings → Agents, onboarding, packaging, milestones, and acceptance matrix.
• docs/protocol.md — channel matrix, transport choices, Runtime RPC/SSE wire rules, versioning, and schema requirements.
• docs/storage.md — SQLite identity, indexing, pagination, query budgets, audit findings, and performance verification.
• docs/proposal.md — project rationale, audience, and product direction.
• docs/test.md — manual desktop verification plan.
• design/README.md — UI mockup philosophy and design notes.

Community

• CONTRIBUTING.md — development workflow and pull request expectations.
• SUPPORT.md — support scope and telemetry privacy guidance.
• SECURITY.md — vulnerability reporting policy and current launch gate.
• CODE_OF_CONDUCT.md — community standards and confidential reporting.

Never post credentials or raw production telemetry in a public issue. Use synthetic fixtures or redact prompts, SQL, URLs, headers, identifiers, paths, and customer data.

Repository Layout

otelux/
  apps/
    desktop/            # Electron desktop workbench
  packages/
    types/              # Shared telemetry types
    protocol/           # DataSource interface and query/result shapes
    engine/             # Ingest, query, layout, subscriptions, storage boundary
    engine-node/        # Node local-storage adapter
    local-runtime/      # Storage, engine, OTLP, MCP, settings, lifecycle
    receiver/           # OTLP receiver
    mcp-server/         # Read-only MCP JSON-RPC tools
    adapter-direct/     # In-process DataSource adapter
    adapter-http/       # Browser-safe authenticated JSON-RPC/SSE adapter
    ui/                 # React workbench and primitives
  plugins/
    otelux/             # Shared Claude/Codex skills + MCP launcher/bridge
  fixtures/             # OTLP JSON fixtures for traces, logs, and metrics
  docs/                 # Canonical project docs
  design/               # Single-file UI mockup and notes

Develop

Requires Node 22.12+ and npm 10.9.x.

npm install
npm run lint
npm run typecheck
npm run test
npm run build

Launch the desktop app in development:

npm run -w @otelux/desktop dev

Build the desktop app:

npm run -w @otelux/desktop build

Test the current 0.1.5 local agent plugin after starting the desktop app:

# Codex
codex plugin marketplace add .
codex plugin add otelux@otelux-plugins

# Claude Code
claude plugin marketplace add /absolute/path/to/otelux
claude plugin install otelux@otelux-plugins

Both hosts currently load the same four skills and connect to the desktop's authenticated, read-only MCP listener. The target plugin starts or discovers the shared local runtime and no longer requires Desktop. See plugins/otelux/README.md for current usage and docs/arch.md for the migration plan.

Exercise the current Linux packaging target while release work is in progress:

npm run -w @otelux/desktop package

Current Status

Open-source prerelease under active hardening. The latest published Linux x64/arm64 .deb and AppImage prerelease is v0.1.17, built from the current shared-runtime and bundled-CLI baseline. @otelux/local-runtime owns storage, engine, OTLP, MCP, Runtime API, settings, lifecycle, canonical data-home migration, and nonce-protected runtime state. Desktop starts or reconnects to it as an HTTP/SSE client, and a bundled oteluxctl provides lifecycle/status commands, while the 0.1.5 plugin remains a Desktop launcher companion. Desktop exposes configurable background ingestion with a menu-bar control and an explicit full-stop action; direct MCP packaging, CLI browser open/public distribution, automatic upgrade rollback, and the runtime-served browser workbench remain planned. Start with docs/getting-started.md. See the specification's Current Baseline for implemented capabilities, docs/arch.md for the architecture transition, docs/plan.md for future work, and docs/release-sprint.md for finite release/publication gates.

License

MIT.