detrix

Detrix is a debugging and observability daemon that lets an AI agent insert observation points into a running application without code changes or restarts. It connects to your app's debugger (Python, Go, or Rust) to set logpoints that evaluate expressions and log values while the program continues to run. This enables you to watch variables and expressions in real time, locate bugs, and reason about behavior from the agent’s perspective using natural-language prompts. You can attach Detrix to local processes or run it alongside services in Docker, and you can use Claude Code, Cursor, or Windsurf to request observations, inspect variables, or query historical observations. The system is designed to minimize overhead and avoid exposing sensitive data by default through configurable blacklist/whitelist in detrix.toml. To start, initialize Detrix, attach it to your app, and then tell your agent which line or variable to observe. The agent will place non-intrusive observation points that log results without pausing execution, enabling fast, production-safe debugging in Go, Python, or Rust apps (and with support for Dockerized environments).

Typical workflow: install Detrix, initialize storage, instrument your app via the agent or embed detrix.init() in your code, and then use your MCP client (Claude Code, Cursor, Windsurf) to observe a specific line or variable. The agent will report the observed values back as structured events, which you can filter, search, and analyze to diagnose issues such as incorrect calculations, type mismatches, or unexpected state changes. For cloud or container deployments, Detrix can fetch sources automatically so the agent can locate the right lines even in remote or containerized environments.

Prerequisites:

• Docker or a compatible container runtime installed on your system
• Optional: access to the Detrix Docker image (ghcr.io/flashus/detrix:latest)

Installation options:

Option A: Run Detrix via Docker (recommended for quick start)

1. Ensure Docker is running
2. Start Detrix in your environment: docker run -i ghcr.io/flashus/detrix:latest
3. If you want Detrix to manage a project, initialize its config/storage inside the container as needed and follow the on-screen prompts or consult the docs for detrix init behavior.

Option B: Build from source (advanced)

1. Install Rust toolchain (Rust 1.60+ recommended):
   • macOS/Linux: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   • Windows: rustup-init.exe
2. Clone the repository and build: git clone https://github.com/flashus/detrix.git cd detrix cargo install --path .
3. Initialize and run Detrix locally: detrix init detrix run

Option C: Install via package managers (if provided in your environment)

• macOS/Homebrew: brew install flashus/tap/detrix (if available)
• Other package managers: follow the official installation guide in the docs

After installation, initialize and connect to your app as described in the Quick Start guide (detrix init, then integrate with your app and attach via your MCP workflow).

Tips and common issues:

• If you’re running inside Docker, ensure the Detrix container has access to your target process or host networking as required by your environment.
• By default, Detrix applies sensitive-data protections with a blacklist/whitelist mechanism in detrix.toml. Review and customize these lists to prevent leaking secrets in logs.
• You can customize observation behavior (throttle, sample, first-hit, interval) to control how often observations are recorded.
• For cloud or remote setups, Detrix can fetch source files automatically so the agent can locate the correct lines without embedding instrumentation in your code.
• When embedding detrix.init() in your app, you can use a unique name (e.g., detrix.init(name="my-app")) to organize observations per application/context.
• If observing in production, prefer logpoints that do not pause execution and minimize performance overhead.
• For secure deployments, consider whitelisting variables that are safe to observe and blacklisting sensitive data (e.g., credentials, tokens).
• If you encounter connectivity issues between the agent and Detrix, verify network routes, Docker container permissions, and correct MCP configuration in your client (Claude Code, Cursor, Windsurf) setup.