Auditor Configuration Reference

This document describes how to configure Lucid auditors through environment variables, pod annotations, the auditors.yaml manifest, and LucidWorkspace YAML definitions.

LucidWorkspace: Declarative Auditor Configuration

The preferred way to configure auditors is via a LucidWorkspace YAML resource, which declares workspace-wide defaults for auditor chains and settings, and an agents[] array for per-agent definitions including model configuration. The legacy policyRef and policies fields are replaced by the auditorSettings cascade (org → workspace → agent):

apiVersion: lucid.io/v1alpha1
kind: LucidWorkspace
metadata:
  name: my-workspace
spec:
  defaults:
    auditorChain:
      preRequest:
        - auditorId: lucid-llm-judge-auditor
        - auditorId: lucid-llm-judge-auditor
      postResponse:
        - auditorId: lucid-llm-judge-auditor
    auditorSettings:
      lucid-llm-judge-auditor:
        injectionThreshold: { value: 0.9, enforced: true }
        blockOnInjection: { value: true, enforced: true }
      lucid-llm-judge-auditor:
        enablePii: { value: true }

  agents:
    - name: my-agent
      model:
        id: qwen3-8b
      auditorSettings:
        lucid-llm-judge-auditor:
          injectionThreshold: { value: 0.8 }

Deploy with: lucid apply -f workspace.yaml

See the LucidWorkspace schema in packages/external/lucid-schemas/lucid_schemas/workspace_spec.py for the full specification.

Legacy Configuration Methods

The methods below configure auditors at the infrastructure level. For new deployments, prefer LucidWorkspace for a unified, portable configuration.

Configuration Precedence

Configuration values are resolved in the following order (highest priority first):

Environment Variables - Highest priority, overrides all other sources
Pod Annotations - Kubernetes pod-level configuration
auditors.yaml Manifest - Policy-as-code definitions
Hardcoded Defaults - Fallback values in auditor code

Configuration Methods

1. Environment Variables

Environment variables are the primary configuration method for auditors.

# In auditors.yaml
chain:
  - name: lucid-llm-judge-auditor
    image: "lucid-llm-judge-auditor:latest"
    port: 8090
    env:
      INJECTION_THRESHOLD: "0.8"
      INJECTION_BLOCK_ON_DETECTION: "true"

2. Pod Annotations

Kubernetes pod annotations allow per-workload configuration:

apiVersion: v1
kind: Pod
metadata:
  labels:
    lucid.io/secured: "true"
  annotations:
    lucid.computing/auditors: "injection,toxicity"
    lucid.computing/injection-threshold: "0.9"
    lucid.computing/toxicity-block: "true"
spec:
  containers:
    - name: my-llm
      image: my-llm:latest

Supported annotations:

Annotation	Description	Default
`lucid.computing/auditors`	Comma-separated list of auditors	`""`
`lucid.computing/audit-mode`	Audit mode (`enforce`, `observe`)	`enforce`
`lucid.computing/skip-audit`	Skip auditing for this pod	`false`

3. Auditors YAML Manifest

Define your audit chain in auditors.yaml:

chain:
  - name: string          # Unique name for the auditor instance
    description: string   # (Optional) Description
    image: string         # OCI image tag
    port: integer         # Internal port (e.g., 8090)
    env:                  # Environment variables
      KEY: VALUE

4. Auditor Catalog (`auditors.yaml`)

The auditor catalog at deploy/applications/catalog/auditors.yaml is the single source of truth for all auditor definitions. It drives both the backend API and the Observer UI's auditor configuration forms.

Each auditor entry supports the following fields:

Field	Type	Description
`id`	string	Unique auditor identifier (e.g., `lucid-llm-judge-auditor`)
`name`	string	Human-readable display name
`description`	string	Detailed description
`category`	enum	One of: `security`, `compliance`, `observability`, `evaluation`, `provenance`
`phase`	enum	Pipeline phase: `artifact_safety`, `input_guarding`, `execution_monitoring`, `output_policy`
`icon`	string	Lucide icon name for the UI
`color`	string	Color theme for the UI
`defaultPort`	integer	Default container port
`envVariables`	list	Environment variable definitions (see below)
`policyOptions`	list	UI-driven policy option definitions (see below)
`defaultPolicy`	object	Default policy with rules and enforcement mode

Claim Definitions & Detection Settings

Each auditor entry includes a claims array. Each claim carries a settings list of ClaimSettingDefinition objects that describe the detection parameters the auditor accepts. The Observer UI auto-generates configuration forms from these settings.

claims:
  - name: injection_risk
    type: number
    description: "Prompt injection risk score"
    settings:
      - key: injection_threshold
        label: "Injection Threshold"
        type: number
        default: 0.9
        min: 0
        max: 1
        step: 0.1
        control: slider
  - name: pii_found
    type: boolean
    description: "Personal information detected"
    settings:
      - key: pii_action
        label: "PII Action"
        type: string
        default: "redact"
        control: select
        options: ["redact", "block", "warn"]

Setting Type	Rendered As	Extra Fields
`number`	Slider or number input	`min`, `max`, `step`, `unit`
`boolean`	Toggle	—
`string`	Text input or select	`options` (for select), `control` hint
`string[]`	Tag input	`options` (suggestions)

Detection setting values are stored in AuditorPolicy.detection and passed to auditors as per-claim overrides via lucid_context["detection_overrides"].

Common Auditor Configuration

These variables are common across all auditors:

Variable	Default	Description
`PORT`	varies	Server port (8090-8098 depending on auditor)
`LUCID_AUDITOR_ID`	varies	Unique auditor identifier
`LUCID_SESSION_ID`	`demo-session`	Session identifier for audit logs

Injection Auditor

Port: 8090

Variable	Default	Description
`INJECTION_THRESHOLD`	`0.8`	Detection threshold (0.0-1.0). Higher = more strict.
`INJECTION_BLOCK_ON_DETECTION`	`true`	Block requests when injection is detected.
`INJECTION_BAN_SUBSTRINGS`	`ignore previous,...`	Comma-separated list of banned substrings.
`INJECTION_MAX_TOKEN_LIMIT`	`4096`	Maximum tokens allowed in input.
`INJECTION_INVISIBLE_CHAR_CHECK`	`true`	Check for invisible/zero-width Unicode characters.
`INJECTION_TOXICITY_THRESHOLD`	`0.7`	Toxicity score threshold for flagging.

Toxicity Auditor

Port: 8093

Detection Thresholds

Variable	Default	Description
`TOXICITY_MODEL`	`unitary/toxic-bert`	Toxicity detection model.
`TOXICITY_THRESHOLD`	`0.7`	Overall toxicity threshold (0.0-1.0).
`TOXICITY_SEVERE_THRESHOLD`	`0.5`	Severe toxicity threshold.
`TOXICITY_THREAT_THRESHOLD`	`0.6`	Threat detection threshold.
`TOXICITY_INSULT_THRESHOLD`	`0.7`	Insult detection threshold.
`TOXICITY_IDENTITY_ATTACK_THRESHOLD`	`0.5`	Identity attack threshold.

Behavior

Variable	Default	Description
`TOXICITY_BLOCK_ON_DETECTION`	`true`	Block response on detection.
`TOXICITY_REPLACEMENT_MESSAGE`	`Content filtered for safety`	Replacement text for blocked content.
`TOXICITY_MULTILINGUAL`	`true`	Enable multilingual toxicity detection.

Deployment Type Configuration

The deployment_type field on an environment spec determines which components are provisioned. Set it at the top level of the spec:

apiVersion: lucid.io/v1alpha1
kind: LucidEnvironment
metadata:
  name: my-backend
spec:
  deployment_type: model
  agents:
    - name: backend-llm
      model:
        id: meta-llama/Llama-3.3-70B

Value	Components Provisioned	Description
`model`	Model + Auditors	Headless API backend deployed via nanobot

See the Deployment Modes guide for usage patterns.

Workflow API Endpoints

Workflows are managed through the Verifier API. Key endpoints:

Method	Endpoint	Description
`POST`	`/api/v1/workflows`	Create a new workflow
`GET`	`/api/v1/workflows`	List all workflows
`GET`	`/api/v1/workflows/{id}`	Get workflow details
`PUT`	`/api/v1/workflows/{id}`	Update workflow graph
`POST`	`/api/v1/workflows/{id}/deploy`	Deploy a workflow
`POST`	`/api/v1/workflows/{id}/stop`	Stop a running workflow
`GET`	`/api/v1/workflows/{id}/passport`	Get composite workflow passport

See the Workflows concept page for schema details.

MCP Environment Variables

Environment variables for configuring MCP tool exposure and the MCP Gateway.

Per-Service MCP Configuration

Variable	Default	Description
`MCP_ENABLED`	`true`	Enable or disable the `/mcp` endpoint on a service
`MCP_TOOLS_PATH`	`/mcp`	Path where MCP tools are served
`MCP_METADATA_PATH`	`/.well-known/mcp`	Path for MCP tool discovery metadata
`MCP_MAX_CONCURRENT_CALLS`	`10`	Maximum concurrent MCP tool invocations

MCP Gateway Configuration

Variable	Default	Description
`MCP_GATEWAY_ENABLED`	`true`	Enable the MCP Gateway service
`MCP_GATEWAY_PORT`	`8100`	Port for the MCP Gateway
`MCP_GATEWAY_OAUTH_ISSUER`	`""`	OAuth 2.1 issuer URL for external client auth
`MCP_GATEWAY_MTLS_ENABLED`	`true`	Require mTLS for internal service-to-service calls
`MCP_GATEWAY_DISCOVERY_INTERVAL`	`30`	Seconds between service discovery refreshes

See the MCP concept page for architecture details.

VAP Environment Variables

Environment variables specific to Verifiable Agent Pod features.

Detection Settings

Detection settings — the parameters that control how an auditor produces claims (thresholds, entity lists, modes) — are declared as keyword-only parameters on @claims-decorated methods. The SDK auto-extracts them into ClaimSettingDefinition objects on each ClaimDefinition.

At runtime, detection settings are resolved in this order:

lucid_context["detection_overrides"] -- Per-claim overrides from the active AuditorPolicy (highest priority)
Environment variables -- Traditional per-auditor env vars (fallback)
@claims kwarg defaults -- Decorator parameter defaults (lowest priority)

Existing auditor deployments that rely on environment variables continue to work unchanged.

Per-Policy Detection Overrides

Each AuditorPolicy can carry a detection JSON column with per-claim setting overrides:

{
  "injection_risk": { "injection_threshold": 0.7 },
  "pii_found": { "pii_action": "redact", "pii_types": ["SSN", "CREDIT_CARD"] }
}

The Gateway passes these overrides via lucid_context["detection_overrides"], and the SDK merges them into the @claims method kwargs before invocation.

Auditor Presets

Presets provide pre-tuned configurations for common risk profiles. Apply them via the API:

# Per-auditor preset (Starter, Balanced, or Strict)
POST /api/v1/workspaces/{id}/apply-preset
{ "auditor": "guardrails", "tier": "balanced" }

# Quick-start bundle (configures multiple auditors at once)
POST /api/v1/workspaces/{id}/apply-preset
{ "bundle": "solo_builder" }

Each preset sets both Detection Rules (detection overrides on the AuditorPolicy) and Response Rules (Cedar policies that map claims to decisions). Three quick-start bundles are available:

Bundle	Auditors	Target
`solo_builder`	2 auditors at Starter tier	Individual developers
`production_team`	2 auditors at Balanced tier	Customer-facing teams
`regulated_enterprise`	2 auditors at Strict	Regulated industries

See the Auditor Concepts page for detailed preset values per auditor.

Best Practices

Use environment variables for configuration - Easy to override per-deployment
Set thresholds based on your use case - More sensitive applications need stricter thresholds
Enable logging - Audit trails are essential for compliance
Test in observe mode first - Use audit-mode: observe to monitor before enforcing
Secure the MCP Gateway - Always configure MCP_GATEWAY_OAUTH_ISSUER in production