Config

config() is the single public API for Crux project configuration. Use it for policy, local tooling, runtime hooks, persistence, observability, plugins, and explicit experimental opt-ins.

Do not repeat prompts, contexts, tools, agents, flows, registries, or skills in config(). Author those values in normal TypeScript modules and export them. Local tooling discovers them from source.

import { config } from '@use-crux/core'

export default config({
  quality: {
    defaults: { replay: 'record-new' },
  },
  lint: {
    profile: 'recommended',
  },
  generation: {
    autoEscape: true,
  },
})

An empty config is valid:

import { config } from '@use-crux/core'

export default config({})

Behavior

config() applies immediately when the module is imported. Node module caching means a normal crux.config.ts module runs once per process.

When local tooling imports the config with CRUX_INDEX=1, Crux returns an inert config object: no observability transport, Runtime Bridge, store, middleware, tokenizer, or plugin side effects are installed. This is what crux config inspect uses.

Outside index mode, config application is transactional: persistence and explicit observability are installed before user plugins, the Runtime Bridge connects after the prompt registry exists, and dispose() tears down the bridge before restoring config-owned hooks, plugins, and observability. This keeps plugin setup predictable without adding another public setup API.

config() is one-config-per-process. Re-running it replaces the previous active installation before applying the new one, so hot reload does not stack middleware or duplicate plugin hook fan-out. Disposing an older returned Crux object is safe after a later config() call; it cannot clear the new active installation. Per-request or multi-tenant config scoping is intentionally out of scope for this process-global API.

devtools and observability have different ownership:

• devtools.serverUrl is the local development fallback. When no explicit observability transport is configured, Crux installs the devtools transport before user plugins.
• observability.enabled: false, observability.transport, or observability.serverUrl makes the observability domain own the transport. In that case devtools does not install its fallback transport, and user plugins see the explicit observability state.

Shape

interface CruxConfig {
  quality?: QualityConfig
  lint?: CruxLintConfig
  indexer?: CruxIndexerConfig
  experimental?: CruxExperimentalConfig
  runtime?: RuntimeEngineDefinition
  persistence?: CruxPersistenceConfig
  generation?: CruxGenerationConfig
  devtools?: CruxDevtoolsConfig
  observability?: CruxObservabilityConfig
  plugins?: readonly CruxPlugin[]
}

quality

Quality config controls discovery, persistence, redaction, and run defaults. Model, judge, and embedding providers belong in eval code, not in config.

export default config({
  quality: {
    id: 'support-agent',
    dir: '.crux/quality',
    include: ['evals/**/*.eval.ts', 'src/**/*.eval.ts'],
    redact: ['customer.email', 'metadata.privateNote'],
    defaults: {
      trials: 2,
      concurrency: 4,
      timeoutMs: 90_000,
      replay: 'record-new',
    },
  },
})

See Quality and crux quality.

lint

Lint config controls authored Project Index findings. It does not run ESLint or TypeScript checks.

export default config({
  lint: {
    profile: 'strict',
    rules: {
      'definition.missing_eval_coverage': { severity: 'error' },
      'prompt.missing_output_schema': { enabled: false },
    },
  },
})

See Index Lint.

indexer

Indexer config is inert data stored by @use-crux/core and enforced by @use-crux/indexer. Loading an allowlisted extension imports JavaScript from node_modules; treat it like trusted build tooling.

export default config({
  indexer: {
    extensions: [
      {
        package: '@acme/crux-indexer',
        export: 'default',
        version: '^1.0.0',
      },
    ],
    trust: {
      mode: 'allowlisted',
      allow: ['@acme/crux-indexer'],
    },
  },
})

See Writing an Indexer Extension.

experimental.indexer

Experimental config is unstable by design. Options here may move, rename, or graduate before a stable release. Stable-looking backend switches do not belong under indexer.

experimental.indexer.native and experimental.indexer.nativeAst are independent:

• native controls semantic enrichment. When enabled, TypeScript-Go owns semantic project setup, checker calls, declaration lookup, and AST traversal.
• nativeAst controls the first static AST/source pass. It can use Rust/Oxc without selecting the native semantic backend.

experimental.indexer.nativeAst is covered by the native AST beta gate before release promotion: Rust/Oxc output must match the TypeScript Static Index baseline after canonical normalization, including lint findings, source graph rows, cache behavior, and TypeScript extension fallback. Node can still start for config inspection or trusted TypeScript extension work. If native AST diagnostics report worker startup, fallback, or Node-start failures, remove the flag or set it to false to return to the TypeScript baseline.

export default config({
  experimental: {
    indexer: {
      native: {
        engine: 'tsgo',
        tsserverPath: '/path/to/tsgo',
      },
      nativeAst: {
        frontend: 'oxc',
      },
    },
  },
})

See Project Index semantic backend selection.

generation

Generation config installs cross-cutting behavior for prompt resolution and adapter execution. Model choices usually belong in prompt, agent, eval, or adapter code.

export default config({
  generation: {
    tokenizer: (text) => Math.ceil(text.length / 4),
    autoEscape: true,
    securityWarnings: process.env.NODE_ENV !== 'production',
  },
})

See Prompt execution and Security warnings.

runtime

Runtime config installs the durable Runtime Engine used by name-bound, event-bound, time-bound, and background APIs.

import { config } from '@use-crux/core'
import { serverless } from '@use-crux/core/runtime'
import { postgres } from '@use-crux/postgres/runtime'
import { qstash } from '@use-crux/upstash/runtime'

export default config({
  runtime: serverless({
    store: postgres(),
    wake: qstash(),
  }),
})

Use node() for local/test execution, serverless({ store, wake }) for HTTP-woken deployments, or convex() from @use-crux/convex/runtime for Convex-hosted runtime work. Runtime config is a stable top-level domain, not experimental.runtime.

See Runtime Engine for the API reference and Runtime guides for deployment shapes.

persistence

Persistence config installs explicit runtime records. Crux does not infer durability, tenancy, or data locality from source discovery.

import { inMemoryRecordStore } from '@use-crux/core/storage'

export default config({
  persistence: {
    records: inMemoryRecordStore(),
  },
})

See Storage.

devtools

Use devtools for the local UI/control/tunnel domain and Runtime Bridge peers. Use observability.serverUrl when application runtime code should send records to a known local server or tunnel.

export default config({
  devtools: {
    serverUrl: 'http://localhost:4400',
    bridge: {
      transport: 'ws',
      runtimeName: 'local-node-worker',
    },
  },
})

See Devtools Integration and Runtime Bridge.

observability

Use observability for deliberate export, tunnel/serverless delivery, or custom transport behavior. For ordinary same-machine local devtools, devtools.serverUrl or withDevtools() is still enough.

When observability.enabled is false, Crux explicitly disables the configured observability transport for this config instance. When observability.serverUrl is set, Crux creates an HTTP transport to that server. When observability.token is set, that token is sent as bearer auth for the scoped devtools ingest endpoint. When observability.transport is set, that custom transport wins.

export default config({
  observability: {
    serverUrl: process.env.CRUX_OBSERVABILITY_URL,
    token: process.env.CRUX_DEVTOOLS_TOKEN,
    delivery: {
      maxPendingDeliveries: 250,
      retryDelayMs: 100,
      maxRetryDelayMs: 5000,
    },
  },
})

See Observability.

plugins

Plugins install hooks in order. Each plugin receives the cumulative hook state from all previous plugins. Cleanup runs when the returned Crux object is disposed. Cleanup hooks may return a promise; Crux starts cleanup in reverse install order, and plugin runners that expose async disposal wait for those promises before reporting shutdown complete.

export default config({
  plugins: [
    {
      name: 'my-plugin',
      install(hooks) {
        return {
          observability subscribers: {
            tool.call start records(event) {
              console.log(event.toolName)
            },
          },
        }
      },
    },
  ],
})

See Observability plugins.

Inspect Effective Config

Use crux config inspect to see the effective config, defaults, origins, and config-load diagnostics:

crux config inspect
crux config inspect --json
crux config inspect --cwd packages/backend
crux config inspect --config crux.config.ts

Every value is tagged with where it came from: default, config, package metadata, or a bound runtime value. Broken config imports degrade to an all-defaults view with diagnostics instead of failing the inspection command.

See crux config.