1.3.0 — Linux eBPF + Agent Mode

Release Notes

New Features

detrix agent — Standalone Agent Subcommand

A lightweight binary deployed on each observed machine that runs the eBPF stack
locally and streams data to a centralized detrix server over gRPC.

• Server-side: AgentConnectionManager manages agent connections with
  lock-split registration, SQLite batch upserts, and connection_requests
  tracking for in-flight request cancellation.
• RemoteAdapter: Proxies DapAdapter trait calls to agents transparently.
  Includes circuit breaker (3 timeouts in 60s → open, 30s cooldown → half-open)
  and 30s last_confirmed_at Ping cooldown.
• Agent binary: /proc scanner with PID-reuse detection (inode tracking),
  5-minute re-registration cooldown, event backpressure (bounded channel with
  DropCountUpdate), and Prometheus /metrics + /health endpoint.
• CLI: detrix agent start / scan / status subcommands.
• Auth: Bearer token authentication via SHA-256(token) comparison. Separate
  from JWT/static user auth.
• Zero proto leakage: AgentConnectionManager uses only domain types; proto
  conversion happens at the gRPC boundary.
• Connection ID determinism: SHA256(name|language|workspace_root|hostname)
  means metrics auto-migrate when agents restart with new agent_id.
• Multi-tenant: Agent connections are user_id = None (visible to all users).

Configuration

New [agent] section in detrix.toml:

# Server-side (agent auth)
[agent]
agent_tokens = ["<sha256-of-token>"]
# Set this to the oldest agent version you intend to support.
min_compatible_agent_version = "1.3.0"

File sources

New AgentFileSource — highest-priority file source for agent connections,
fetches file content via ReadFile command over the gRPC stream.

SourceKind enum

New SourceKind::Agent variant for VFS source priority configuration.

Go and Rust eBPF capture

• Profile-driven eBPF capture now supports both Go and Rust agent connections
  on Linux.
• Rust observation supports bounded scalar, pointer/reference, string, slice,
  vector, fixed-array, enum, and inline aggregate captures when usable DWARF
  locations are available.
• Rust composite values use a bounded wire representation and fail closed for
  unsupported or optimized-out layouts instead of guessing from type names or
  raw byte sizes.
• Rust eBPF remains an explicit backend choice; Rust auto selection is kept
  behind its release gate while DAP remains the safe fallback.

Reliability and release validation

• Added native Linux eBPF release-gate coverage for Go and Rust agent flows,
  including reconnect, sustained event accounting, composite values, and
  unavailable/optimized-out variables.
• Debugger event subscriptions now recover across an automatic DAP session
  restart without prematurely removing the logical connection.

Testing

• 14 agent integration tests (connection ID determinism, circuit breaker,
  proto conversions, scanner, event messages).
• Privileged Linux coverage for Go and Rust eBPF capture, including nested and
  composite values, reconnects, sustained accounting, and fail-closed paths.
• Docker deployment files: Dockerfile.agent, docker-compose.agent.yml,
  detrix.agent.toml.

Install detrix 1.3.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/flashus/detrix/releases/download/v1.3.0/detrix-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/flashus/detrix/releases/download/v1.3.0/detrix-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install flashus/tap/detrix

Download detrix 1.3.0

File	Platform	Checksum
detrix-aarch64-apple-darwin.tar.xz	Apple Silicon macOS	checksum
detrix-x86_64-apple-darwin.tar.xz	Intel macOS	checksum
detrix-x86_64-pc-windows-msvc.zip	x64 Windows	checksum
detrix-x86_64-pc-windows-msvc.msi	x64 Windows	checksum
detrix-aarch64-unknown-linux-gnu.tar.xz	ARM64 Linux	checksum
detrix-x86_64-unknown-linux-gnu.tar.xz	x64 Linux	checksum

1.2.0 2026-03-21 — Multi-Tenant Authentication

Release Notes

⚠️ BREAKING CHANGES — This release introduces multi-tenant authentication.
Existing single-user configurations require migration (see below).

Breaking Changes

Metric.created_by removed — replaced by user_id + agent_id

The created_by field has been removed from Metric. It is replaced by:

• user_id — the authenticated user identity (from static token or JWT sub claim)
• agent_id — the MCP bridge session UUID (from X-Detrix-Client-Id header)

Migration: Re-add metrics after upgrading. Pre-migration metrics stored with
user_id = NULL are not accessible to non-Admin users (see note below).

Config: api.auth.bearer_token removed

The top-level bearer_token config key is no longer supported.

Before (v1.0):

[api.auth]
bearer_token = "my-secret-token"

After (v1.1):

[api.auth]
mode = "simple"

[[api.auth.users]]
token = "my-secret-token"
user_id = "default"
role = "admin"

Starting the daemon with no [api.auth] section auto-generates a secure token
(stored at ~/detrix/auth-token) — no config change needed for single-user setups.

Config: Connection.created_by renamed to user_id

The created_by field on the Connection entity has been renamed to user_id
for consistency with Metric.user_id. A database migration (003_connection_user_id.sql)
renames the column automatically on startup.

Security Fixes

• Constant-time token comparison — Bearer tokens are now compared using
  subtle::ConstantTimeEq to prevent timing side-channel attacks.
• Debug output token redaction — StaticUser.token is redacted as
  [REDACTED] in Debug output to prevent token leakage in logs/panics.
• JWT sub claim required — JWTs without a sub claim are now rejected
  with HTTP 401 / gRPC Unauthenticated. Previously, missing sub would silently
  use "anonymous" as user_id, potentially granting shared identity to all
  un-identified callers.

Bug Fixes

• Bridge disable_my_metrics used wrong field — The MCP bridge now correctly
  identifies its own metrics using agentId (the bridge's per-session UUID)
  instead of userId. Previously, the bridge could accidentally miss metrics or
  match other agents' metrics.
• NULL user_id stored as "system" — Metrics with no authenticated user
  now store user_id = NULL in the database instead of the sentinel string
  "system". This prevents scope mismatch when auth is later enabled.
• Non-deterministic find_by_location ordering — SELECT … LIMIT 1 now
  includes ORDER BY created_at ASC to return a deterministic result.
• migrate_connection_id mock missed user_id in conflict detection — The
  in-memory mock now includes user_id in the occupied-location set, matching
  the real SQLite UPDATE OR IGNORE behavior.

Validation Improvements

• Duplicate bearer tokens in [[api.auth.users]] are now rejected at startup.
• Duplicate user_id values in [[api.auth.users]] are now rejected at startup.
• Token length is now limited to 512 characters.
• Starting with the old bearer_token = "..." config now produces a clear error
  message pointing to the migration guide, instead of a confusing startup failure.
• Tenant ID hardening — user_id and agent_id now reject whitespace-only
  strings, control characters, and the reserved __*__ pattern (e.g., __system__,
  __admin__). Invalid values return HTTP 400 / gRPC INVALID_ARGUMENT with
  error code 1008 (INVALID_TENANT_ID).

Performance

• Pre-computed token hashes — SHA-256 hashes of static user tokens are computed
  at construction time instead of on every auth request, eliminating per-request
  allocation in the authentication hot path.
• Zero-allocation public endpoint matching — is_public_endpoint() no longer
  allocates a String per endpoint per request.
• SQL-level group summaries — list_group_summaries_scoped for non-admin users
  now uses a SQL GROUP BY … WHERE user_id = ? query instead of fetching all user
  metrics into memory.

Infrastructure

• DETRIX_FILE_SERVER_HOST env var — The MCP bridge --file-server-host CLI
  argument can now also be set via the DETRIX_FILE_SERVER_HOST environment variable
  (CLI argument takes priority).
• Configurable attach failure window — The DAP attach/launch failure detection
  timeout (default 500ms) can now be configured via attach_failure_window_ms in
  [adapter] config. Useful for high-latency remote/Docker scenarios.

Notes

Pre-migration metrics are not visible to non-Admin users

Metrics stored before the multi-tenant upgrade have user_id = NULL in the
database. After the upgrade, only Admin-scoped callers can read these metrics.
Non-Admin users will not see them in list_metrics / get_metric results.

Resolution: Re-add the metrics after the upgrade. They will be associated
with the authenticated user and become visible normally.

This behavior is intentional by design — there is no safe way to
automatically assign ownership to an anonymous metric after the fact.

Install detrix 1.2.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/flashus/detrix/releases/download/v1.2.0/detrix-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/flashus/detrix/releases/download/v1.2.0/detrix-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install flashus/tap/detrix

Download detrix 1.2.0

File	Platform	Checksum
detrix-aarch64-apple-darwin.tar.xz	Apple Silicon macOS	checksum
detrix-x86_64-apple-darwin.tar.xz	Intel macOS	checksum
detrix-x86_64-pc-windows-msvc.zip	x64 Windows	checksum
detrix-x86_64-pc-windows-msvc.msi	x64 Windows	checksum
detrix-aarch64-unknown-linux-gnu.tar.xz	ARM64 Linux	checksum
detrix-x86_64-unknown-linux-gnu.tar.xz	x64 Linux	checksum

1.2.0 2026-03-21 — Multi-Tenant Authentication

Release Notes

⚠️ BREAKING CHANGES — This release introduces multi-tenant authentication.
Existing single-user configurations require migration (see below).

Breaking Changes

Metric.created_by removed — replaced by user_id + agent_id

The created_by field has been removed from Metric. It is replaced by:

• user_id — the authenticated user identity (from static token or JWT sub claim)
• agent_id — the MCP bridge session UUID (from X-Detrix-Client-Id header)

Migration: Re-add metrics after upgrading. Pre-migration metrics stored with
user_id = NULL are not accessible to non-Admin users (see note below).

Config: api.auth.bearer_token removed

The top-level bearer_token config key is no longer supported.

Before (v1.0):

[api.auth]
bearer_token = "my-secret-token"

After (v1.1):

[api.auth]
mode = "simple"

[[api.auth.users]]
token = "my-secret-token"
user_id = "default"
role = "admin"

Starting the daemon with no [api.auth] section auto-generates a secure token
(stored at ~/detrix/auth-token) — no config change needed for single-user setups.

Config: Connection.created_by renamed to user_id

The created_by field on the Connection entity has been renamed to user_id
for consistency with Metric.user_id. A database migration (003_connection_user_id.sql)
renames the column automatically on startup.

Security Fixes

• Constant-time token comparison — Bearer tokens are now compared using
  subtle::ConstantTimeEq to prevent timing side-channel attacks.
• Debug output token redaction — StaticUser.token is redacted as
  [REDACTED] in Debug output to prevent token leakage in logs/panics.
• JWT sub claim required — JWTs without a sub claim are now rejected
  with HTTP 401 / gRPC Unauthenticated. Previously, missing sub would silently
  use "anonymous" as user_id, potentially granting shared identity to all
  un-identified callers.

Bug Fixes

• Bridge disable_my_metrics used wrong field — The MCP bridge now correctly
  identifies its own metrics using agentId (the bridge's per-session UUID)
  instead of userId. Previously, the bridge could accidentally miss metrics or
  match other agents' metrics.
• NULL user_id stored as "system" — Metrics with no authenticated user
  now store user_id = NULL in the database instead of the sentinel string
  "system". This prevents scope mismatch when auth is later enabled.
• Non-deterministic find_by_location ordering — SELECT … LIMIT 1 now
  includes ORDER BY created_at ASC to return a deterministic result.
• migrate_connection_id mock missed user_id in conflict detection — The
  in-memory mock now includes user_id in the occupied-location set, matching
  the real SQLite UPDATE OR IGNORE behavior.

Validation Improvements

• Duplicate bearer tokens in [[api.auth.users]] are now rejected at startup.
• Duplicate user_id values in [[api.auth.users]] are now rejected at startup.
• Token length is now limited to 512 characters.
• Starting with the old bearer_token = "..." config now produces a clear error
  message pointing to the migration guide, instead of a confusing startup failure.
• Tenant ID hardening — user_id and agent_id now reject whitespace-only
  strings, control characters, and the reserved __*__ pattern (e.g., __system__,
  __admin__). Invalid values return HTTP 400 / gRPC INVALID_ARGUMENT with
  error code 1008 (INVALID_TENANT_ID).

Performance

• Pre-computed token hashes — SHA-256 hashes of static user tokens are computed
  at construction time instead of on every auth request, eliminating per-request
  allocation in the authentication hot path.
• Zero-allocation public endpoint matching — is_public_endpoint() no longer
  allocates a String per endpoint per request.
• SQL-level group summaries — list_group_summaries_scoped for non-admin users
  now uses a SQL GROUP BY … WHERE user_id = ? query instead of fetching all user
  metrics into memory.

Infrastructure

• DETRIX_FILE_SERVER_HOST env var — The MCP bridge --file-server-host CLI
  argument can now also be set via the DETRIX_FILE_SERVER_HOST environment variable
  (CLI argument takes priority).
• Configurable attach failure window — The DAP attach/launch failure detection
  timeout (default 500ms) can now be configured via attach_failure_window_ms in
  [adapter] config. Useful for high-latency remote/Docker scenarios.

Notes

Pre-migration metrics are not visible to non-Admin users

Metrics stored before the multi-tenant upgrade have user_id = NULL in the
database. After the upgrade, only Admin-scoped callers can read these metrics.
Non-Admin users will not see them in list_metrics / get_metric results.

Resolution: Re-add the metrics after the upgrade. They will be associated
with the authenticated user and become visible normally.

This behavior is intentional by design — there is no safe way to
automatically assign ownership to an anonymous metric after the fact.

Install detrix 1.2.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/flashus/detrix/releases/download/clients/go/v1.2.0/detrix-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/flashus/detrix/releases/download/clients/go/v1.2.0/detrix-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install flashus/tap/detrix

Download detrix 1.2.0

File	Platform	Checksum
detrix-aarch64-apple-darwin.tar.xz	Apple Silicon macOS	checksum
detrix-x86_64-apple-darwin.tar.xz	Intel macOS	checksum
detrix-x86_64-pc-windows-msvc.zip	x64 Windows	checksum
detrix-x86_64-pc-windows-msvc.msi	x64 Windows	checksum
detrix-aarch64-unknown-linux-gnu.tar.xz	ARM64 Linux	checksum
detrix-x86_64-unknown-linux-gnu.tar.xz	x64 Linux	checksum

1.1.0 - 2026-02-26

Release Notes

Highlights

• Cloud debugging — Observe code running inside Docker containers and remote hosts. No VPN, no port-forwarding. The AI agent connects to a Detrix daemon deployed alongside your service.
• Multi-expression metrics — Single observation point captures multiple variables simultaneously.

Added

Cloud Debugging

• Daemon auto-discovery — Clients register with the daemon at startup; the MCP bridge discovers them automatically via advertise_url
• Virtual File System (VFS) — Transparently fetches source files for the agent. Three configurable sources: bridge (from AI agent workspace), control_plane (from app container), disk (local path). Configurable priority order in [vfs] config section
• Multi-connection MCP — MCP bridge handles multiple concurrent AI agent sessions with workspace-aware file serving
• Connection reference counting — Shared DAP connections are safely used by multiple concurrent MCP clients
• Container restart metric migration — Metrics and connections survive container restarts automatically
• Admin endpoints — New REST endpoints for daemon administration (/api/v1/admin/*)
• Docker cloud E2E tests — Comprehensive test suite for Docker-based cloud debugging workflows

Remote App Control

• wake / sleep MCP tools — Resume or suspend a remote app's debugger on demand. Zero overhead when sleeping; agent wakes the app before adding metrics
• MCP bridge fallback — If daemon forwarding fails during wake, falls back to direct bridge connection and auto-switches daemon

Authentication & Security

• Secure-by-default daemon — Authentication enabled by default; set DETRIX_TOKEN env var to configure
• Per-daemon credential storage — Each daemon instance stores credentials independently; discovery-first auth flow
• Client ID audit trail — All mutating operations thread a client ID for full audit traceability
• Hardened client auth — Fixed auth bugs in Go and Rust clients; enabled secure-by-default

Metrics

• Multi-expression metrics — Single metric can observe multiple expressions simultaneously (expressions: ["symbol", "quantity", "price"])
• ExpressionValue type with typed projections (numeric, string, boolean)
• GELF output includes per-expression custom fields (_expr_N_name, _expr_N_value)
• Configurable max_expressions_per_metric limit (default: 20)
• Expression merging — Adding a metric at an existing location merges expressions instead of creating a duplicate

MCP Tools

• disconnect_all — Disconnect all adapters and flush state (new tool, total: 29 tools)

Developer Experience

• Relative path resolution in observe tool — works with paths relative to project workspace root
• Smart line suggestion — observe tool suggests the best line when expression is found nearby
• Build info auto-detection in Go and Rust clients
• Docker cloud example — examples/docker-demo/ shows full cloud debugging setup with Go service, Detrix daemon, and AI agent

Clients (v1.1.1)

• Python client: detrix-py v1.1.1 on PyPI
• Go client: github.com/flashus/detrix/clients/go v1.1.1
• Rust client: detrix-rs v1.1.1 on crates.io
• All clients support build info auto-detection and secure auth

Breaking Changes

• WebSocket API: Field names changed from snake_case to camelCase
  (metric_id -> metricId, stack_trace -> stackTrace)
• gRPC/Proto: expression (singular) replaced with expressions (repeated)
• REST API: expression field replaced with expressions array
• Database: Schema consolidated. Requires clean install from v1.0.

Fixed

• Expression safety validation now enforced on config-file metric imports
• Go/Rust client auth bugs resolved; secure-by-default now works correctly
• Inspector no longer returns non-executable locations (function signatures, struct fields) for Go/Rust variable search

Install detrix 1.1.0

Install prebuilt binaries via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/flashus/detrix/releases/download/v1.1.0/detrix-installer.sh | sh

Install prebuilt binaries via powershell script

powershell -ExecutionPolicy Bypass -c "irm https://github.com/flashus/detrix/releases/download/v1.1.0/detrix-installer.ps1 | iex"

Install prebuilt binaries via Homebrew

brew install flashus/tap/detrix

Download detrix 1.1.0

File	Platform	Checksum
detrix-aarch64-apple-darwin.tar.xz	Apple Silicon macOS	checksum
detrix-x86_64-apple-darwin.tar.xz	Intel macOS	checksum
detrix-x86_64-pc-windows-msvc.zip	x64 Windows	checksum
detrix-x86_64-pc-windows-msvc.msi	x64 Windows	checksum
detrix-aarch64-unknown-linux-gnu.tar.xz	ARM64 Linux	checksum
detrix-x86_64-unknown-linux-gnu.tar.xz	x64 Linux	checksum