Devtools Plugin

API reference for connecting @crux/core observability to the local devtools runtime.

import { enableDevtools, withDevtools } from '@crux/core/observability'
import type { RuntimeBridgeOptions } from '@crux/core/runtime-bridge'

This page documents the SDK APIs that connect a Crux application to a running @crux/local devtools server. The devtools surface is for local UI/control/tunnel/bridge behavior; production telemetry and remote collectors are configured through explicit observability config or telemetry plugins. CLI commands, web UI workflows, and TUI navigation live in the @crux/local reference and Devtools guide.

`withDevtools(options)`

Creates a CruxPlugin that installs the canonical local observability transport.

import { config } from '@crux/core'
import { withDevtools } from '@crux/core/observability'

config({
  plugins: [
    withDevtools({
      prompts: [],
      serverUrl: 'http://localhost:4400',
    }),
  ],
})

Signature

function withDevtools(options: DevtoolsOptions): CruxPlugin

Parameters

Field	Type	Default	Description
`prompts`	`Prompt[]`	`[]`	Prompt definitions to include in runtime index snapshots.
`contexts`	`Context[]`	`[]`	Context definitions to include in runtime index snapshots.
`tools`	`FlowToolDef[]`	`[]`	Tool definitions to include in runtime index snapshots.
`paths`	`Map<string, string[]>`	—	Authored namespace paths from `createPrompts()` / `createContexts()`.
`serverUrl`	`string`	—	URL of the running `@crux/local` server.
`sessionId`	`string`	—	Optional session id used to group emitted runtime records.
`bridge`	`boolean \| RuntimeBridgeOptions`	`false`	Enables the local Runtime Bridge command plane for long-lived Node runtimes.

Returns

CruxPlugin with the name crux:devtools. The plugin cleanup hook restores the previously installed observability transport.

`enableDevtools(options)`

Imperative helper for installing the same local devtools transport outside the plugin system. Most applications should prefer config({ devtools: ... }) or withDevtools() when they explicitly need runtime records sent to a local server or tunnel.

Signature

function enableDevtools(options: EnableDevtoolsOptions): () => void

Parameters

Field	Type	Default	Description
`serverUrl`	`string`	—	URL of the running `@crux/local` server.
`prompts`	`Prompt[]`	`[]`	Prompt definitions to snapshot.
`contexts`	`Context[]`	`[]`	Context definitions to snapshot.
`tools`	`FlowToolDef[]`	`[]`	Tool definitions to snapshot.

Returns

Cleanup function that restores the previous observability transport.

Auto-Install Through `config()`

When devtools.serverUrl is explicitly set and no observability transport is configured, config() installs the local devtools transport. Ordinary local Quality runs do not require this boilerplate; the CLI auto-attaches to loopback crux dev origins.

import { config } from '@crux/core'

config({
  devtools: {
    serverUrl: process.env.CRUX_DEVTOOLS_URL,
    bridge: true,
  },
})

Neither withDevtools() nor enableDevtools() starts the server. Start it with crux dev from @crux/local.

Runtime Bridge Types

Runtime Bridge schemas and helper types are exported from @crux/core/runtime-bridge.

import {
  BridgeCommandRequestSchema,
  BridgeCommandResultSchema,
  RuntimeBridgeMessageSchema,
  RuntimePeerHelloSchema,
  connectRuntimeBridge,
  executeRuntimeBridgeCommand,
  getRuntimeBridgeManifest,
} from '@crux/core/runtime-bridge'

The bridge is a local-dev command plane. Long-lived Node runtimes can open a /ws/runtime peer; framework integrations such as @crux/convex use the same contract over HTTP.

Guide: Devtools
Reference: @crux/local
Reference: Observability
Reference: Project Index

Devtools Plugin

On this page