Skip to main content

Source: docs/manual/config-env.md

This page is generated by site/scripts/sync-manual-docs.mjs.

Configuration and Environment

All Cruvero configuration is via environment variables with a CRUVERO_* prefix. There are no configuration files. Variables are loaded at startup by internal/config/config.go and can be set in .env files for local development.

This reference is organized by subsystem. For phase-specific rollout guides, see the sections below the core reference.

Source: internal/config/config.go, .env.example

Core Environment Variables​

Temporal​

  • CRUVERO_TEMPORAL_ADDRESS (default temporal-grpc.dev.gchinfo.com:443)
  • CRUVERO_TEMPORAL_NAMESPACE (default default)
  • CRUVERO_TEMPORAL_TLS (auto or false)

Database​

  • CRUVERO_POSTGRES_URL
  • CRUVERO_DRAGONFLY_ADDR

LLM Providers​

  • CRUVERO_LLM_PROVIDER (openrouter, azure, openai, or google)
  • CRUVERO_LLM_TIMEOUT (default 60s)
  • CRUVERO_LLM_FAILOVER_CHAIN (comma-separated provider order, e.g. openrouter,google,openai,azure)
  • CRUVERO_LLM_FAILOVER_THRESHOLD (default 3)
  • CRUVERO_LLM_FAILOVER_RECOVERY_INTERVAL (default 5m)
  • CRUVERO_LLM_FAILOVER_LATENCY_THRESHOLD (default 0s, disabled)
  • CRUVERO_OPENROUTER_API_KEY
  • CRUVERO_OPENROUTER_MODEL
  • CRUVERO_AZURE_OPENAI_ENDPOINT
  • CRUVERO_AZURE_OPENAI_API_KEY
  • CRUVERO_AZURE_OPENAI_API_VERSION
  • CRUVERO_AZURE_OPENAI_DEPLOYMENT
  • CRUVERO_OPENAI_CHAT_API_KEY
  • CRUVERO_OPENAI_CHAT_MODEL (default gpt-4.1)
  • CRUVERO_OPENAI_CHAT_BASE_URL (default https://api.openai.com/v1)
  • CRUVERO_GOOGLE_API_KEY (used by embeddings and direct Gemini chat provider)
  • CRUVERO_GOOGLE_MODEL (default gemini-2.5-flash)
  • CRUVERO_GOOGLE_BASE_URL (default https://generativelanguage.googleapis.com/v1beta)
  • CRUVERO_GOOGLE_MAX_TOKENS (default 8192)
  • CRUVERO_AZURE_PRICING_JSON (optional, for models-refresh --source azure)
  • CRUVERO_AZURE_CONTEXT_JSON (optional, for models-refresh --source azure)

Agent Runtime​

  • CRUVERO_METACOGNITIVE_ENABLED (default false)
  • CRUVERO_METACOGNITIVE_CHECK_INTERVAL (default 3)
  • CRUVERO_METACOGNITIVE_MAX_REPETITION (default 3)
  • CRUVERO_METACOGNITIVE_ESCALATION_MODEL (optional escalation model id)
  • CRUVERO_TEMPORAL_REASONING_ENABLED (default false)
  • CRUVERO_DEFAULT_FAST_MODEL (optional fast model id for deadline pressure)
  • CRUVERO_DEADLINE_ACTION (escalate or halt; default escalate)
  • CRUVERO_PROVENANCE_ENABLED (default false; enable execution provenance DAG persistence/query)
  • CRUVERO_PROMPT_QUALITY_ENABLED (default true; enable low-context LLM prompt quality scoring)
  • CRUVERO_PROMPT_QUALITY_TIMEOUT (default 2s; timeout per prompt quality evaluation call)
  • CRUVERO_PROMPT_QUALITY_MAX_INPUT_BYTES (default 2048; max evaluator payload bytes)
  • CRUVERO_PROMPT_QUALITY_MODEL (optional; overrides evaluator model, defaults to decision model)

Memory​

  • CRUVERO_MEMORY_EPISODIC_STORE (postgres or redis)
  • CRUVERO_MEMORY_REDIS_TTL
  • CRUVERO_SALIENCE_ENABLED (default true)
  • CRUVERO_MEMORY_SALIENCE_RELEVANCE (default 0.4)
  • CRUVERO_MEMORY_SALIENCE_RECENCY (default 0.3)
  • CRUVERO_MEMORY_SALIENCE_CONFIDENCE (default 0.2)
  • CRUVERO_MEMORY_SALIENCE_USAGE (default 0.1)
  • CRUVERO_MEMORY_SALIENCE_FRESHNESS (default 0.0)
  • CRUVERO_MEMORY_SALIENCE_HALFLIFE (default 24h)
  • CRUVERO_CONTEXT_BUDGET_ENABLED (default false)
  • CRUVERO_CONTEXT_BUDGET_TOKENS (default 8000)
  • CRUVERO_CONTEXT_SYSTEM_TOKENS (default 1000)

Tools and Registry​

  • CRUVERO_COMPOSITE_MAX_DEPTH (default 8; max nested composite invocation depth, 0 disables limit)
  • CRUVERO_COMPOSITE_MAX_STEPS (default 64; max steps allowed per composite execution, 0 disables limit)
  • CRUVERO_TOOL_CONTRACT_POSTCONDITION_MODE (enforce or warn; default enforce)

Supervisor and Trust​

  • CRUVERO_TRUST_ENABLED (default false; enable supervisor trust-based delegation and trust score updates)
  • CRUVERO_TRUST_REVIEW_THRESHOLD (default 0.3; reviewer fallback threshold for low-trust delegates)
  • CRUVERO_TRUST_WEIGHT_SUCCESS (default 0.5; success-rate weight in trust scoring)
  • CRUVERO_TRUST_WEIGHT_QUALITY (default 0.3; quality-score weight in trust scoring)
  • CRUVERO_TRUST_WEIGHT_RECENCY (default 0.2; recency-factor weight in trust scoring)
  • CRUVERO_TRUST_RECENCY_DECAY (default 0.1; recency decay coefficient in trust scoring)

Immune System​

  • CRUVERO_IMMUNE_ENABLED (default false)
  • CRUVERO_IMMUNE_QUARANTINE_THRESHOLD (default 5)
  • CRUVERO_IMMUNE_QUARANTINE_TTL (default 0s, disabled)
  • CRUVERO_IMMUNE_CLEANUP_ENABLED (default true)
  • CRUVERO_IMMUNE_CLEANUP_INTERVAL (default 24h)
  • CRUVERO_IMMUNE_RETENTION_DAYS (default 90)
  • CRUVERO_IMMUNE_TOOL_THRESHOLDS (optional CSV tool:threshold, e.g. sim_git_pr:3,bash_exec:2)
  • CRUVERO_IMMUNE_TOOL_NO_AUTO (optional CSV tool list excluded from auto-quarantine)
  • CRUVERO_IMMUNE_ALERT_ENABLED (default true)
  • CRUVERO_IMMUNE_ALERT_INTERVAL (default 5m)
  • CRUVERO_IMMUNE_ALERT_ANOMALY_DELTA (default 20)
  • CRUVERO_IMMUNE_ALERT_QUARANTINE_DELTA (default 3)
  • CRUVERO_IMMUNE_ALERT_BLOCKED_DELTA (default 10)
  • CRUVERO_IMMUNE_SNAPSHOT_ENABLED (default true)
  • CRUVERO_IMMUNE_SNAPSHOT_DIR (default backups/immune)
  • CRUVERO_IMMUNE_SNAPSHOT_BATCH (default 1000)

Quota and Cost​

  • CRUVERO_QUOTA_ENABLED (default true)
  • CRUVERO_QUOTA_STORE (postgres or dragonfly)
  • CRUVERO_QUOTA_DEFAULT_RPM (default 60)
  • CRUVERO_QUOTA_DEFAULT_RPH (default 1000)
  • CRUVERO_QUOTA_DEFAULT_TPD (default 1000000)
  • CRUVERO_QUOTA_DEFAULT_COST_USD (default 100.0)
  • CRUVERO_QUOTA_WARNING_THRESHOLD (default 0.8)
  • CRUVERO_QUOTA_CRITICAL_THRESHOLD (default 0.95)
  • CRUVERO_QUOTA_DOWNGRADE_MODEL
  • CRUVERO_QUOTA_CLEANUP_ENABLED (default true)
  • CRUVERO_QUOTA_CLEANUP_INTERVAL (default 6h)
  • CRUVERO_QUOTA_USAGE_RETENTION (default 168h)

Audit​

  • CRUVERO_AUDIT_ENABLED (default false)
  • CRUVERO_AUDIT_PII_DETECTION (default false)
  • CRUVERO_AUDIT_PII_TYPES (default email,phone,ssn,cc,ip)
  • CRUVERO_AUDIT_STORE_ORIGINALS (default true)
  • CRUVERO_AUDIT_BUFFER_SIZE (default 50)
  • CRUVERO_AUDIT_RETENTION_DAYS (default 365)
  • CRUVERO_AUDIT_EXPORT_FORMAT (soc2, hipaa, json, csv; default json)
  • CRUVERO_AUDIT_POSTGRES_URL (optional dedicated audit-writer DSN; falls back to CRUVERO_POSTGRES_URL)

Security and Sandboxing​

  • CRUVERO_SANDBOX_MODE (process, gvisor, nsjail; default process)
  • CRUVERO_INPUT_SANITIZATION (default false)
  • CRUVERO_INPUT_SANITIZATION_MODE (block, warn, passthrough; default warn)
  • CRUVERO_OUTPUT_PII_REDACTION (default true)
  • CRUVERO_OUTPUT_CREDENTIAL_SCAN (default true)
  • CRUVERO_OUTPUT_FILTER_MODE (redact, block; default redact)
  • CRUVERO_NETWORK_POLICY_ENABLED (default false)
  • CRUVERO_NETWORK_DEFAULT_POLICY (deny or allow; default deny)
  • CRUVERO_MCP_STRICT_ENDPOINTS (default true; enforce MCP endpoint allowlists)
  • CRUVERO_VAULT_ADDR
  • CRUVERO_VAULT_TOKEN
  • CRUVERO_VAULT_SECRET_PATH_PREFIX (default secret/cruvero)
  • CRUVERO_PYTHON_ALLOW_ALL_IMPORTS (default false)
  • CRUVERO_PYTHON_BLOCK_IMPORTS (comma-separated import blocklist)
  • CRUVERO_PYTHON_MAX_CPU_SECS (default 2)
  • CRUVERO_PYTHON_MAX_MEM_MB (default 256)
  • CRUVERO_PYTHON_MAX_OUTPUT_KB (default 64)
  • CRUVERO_PYTHON_MAX_FILE_KB (default 256)
  • CRUVERO_BASH_ALLOWED_CMDS (comma-separated command allowlist)
  • CRUVERO_BASH_ALLOW_NETWORK (default false)
  • CRUVERO_BASH_MAX_OUTPUT_KB (default 64)
  • CRUVERO_BASH_MAX_FILE_KB (default 256)

Observability​

  • CRUVERO_LOG_LEVEL
  • CRUVERO_HEALTH_CHECK_INTERVAL (default 30s)
  • CRUVERO_WORKER_PROBE_ADDR (default :8082, worker health probe HTTP server)

Backup​

  • CRUVERO_BACKUP_DIR (default backups)
  • CRUVERO_BACKUP_PG_DUMP_BIN (default pg_dump)
  • CRUVERO_BACKUP_PG_RESTORE_BIN (default pg_restore)
  • CRUVERO_BACKUP_PG_DUMP_FORMAT (default custom)
  • CRUVERO_BACKUP_S3_BUCKET (required for S3 upload/download)
  • CRUVERO_BACKUP_S3_PREFIX (default cruvero)
  • CRUVERO_BACKUP_S3_REGION (default us-east-1)
  • CRUVERO_BACKUP_S3_ENDPOINT (optional S3-compatible endpoint)
  • CRUVERO_BACKUP_S3_FORCE_PATH_STYLE (default false; often required for MinIO)
  • CRUVERO_BACKUP_S3_ACCESS_KEY_ID / CRUVERO_BACKUP_S3_SECRET_ACCESS_KEY / CRUVERO_BACKUP_S3_SESSION_TOKEN (optional static credentials)
  • CRUVERO_BACKUP_AUDIT_ARCHIVE_DAYS (default 30)
  • CRUVERO_BACKUP_AUDIT_ARCHIVE_BATCH_CAP (default 250000; max rows exported per archive run)

UI​

  • CRUVERO_UI_COST_CACHE_TTL (default 30s)
  • CRUVERO_UI_ADMIN_TOKEN (required for POST /api/quota/reset and POST /api/quota/override)

Production API (cmd/api)​

VariableDefaultDescription
CRUVERO_API_PORT8900API listen port
CRUVERO_API_READ_TIMEOUT30sHTTP read timeout
CRUVERO_API_WRITE_TIMEOUT60sHTTP write timeout
CRUVERO_API_IDLE_TIMEOUT120sHTTP idle timeout
CRUVERO_API_SHUTDOWN_TIMEOUT15sGraceful shutdown timeout
CRUVERO_API_AUTHnoneAuth mode: none, keycloak, apikey
CRUVERO_API_JWKS_URL—JWKS endpoint for JWT verification
CRUVERO_API_ISSUER—Expected JWT issuer
CRUVERO_API_AUDIENCE—Expected JWT audience
CRUVERO_API_API_KEYS—Comma-separated static API keys for apikey auth mode
CRUVERO_API_RATE_LIMIT1000Requests per minute per tenant
CRUVERO_API_RATE_LIMIT_BURST50Per-tenant burst allowance (requests per second limiter)
CRUVERO_API_CORS_ORIGINS*Comma-separated CORS allowlist
CRUVERO_API_CORS_MAX_AGE3600CORS preflight cache max-age (seconds)
CRUVERO_OTEL_ENDPOINT—OTLP trace exporter endpoint
CRUVERO_OTEL_INSECUREfalseUse insecure OTLP transport

MCP Variables​

See MCP Integration.

  • CRUVERO_MCP_ENDPOINTS_<SERVER> (comma-separated allowed endpoint URLs for server-specific MCP endpoint pinning)
  • CRUVERO_CODE_EXEC_MCP_REQUIRED (default false; when true, python_exec/bash_exec fail closed if MCP mcp-code-exec route is unavailable in http|gateway mode)

Phase 10: Neuro-Inspired Intelligence​

10A Metacognitive Monitoring​

  • CRUVERO_METACOGNITIVE_ENABLED (default false)
  • CRUVERO_METACOGNITIVE_CHECK_INTERVAL (default 3)
  • CRUVERO_METACOGNITIVE_MAX_REPETITION (default 3)
  • CRUVERO_METACOGNITIVE_ESCALATION_MODEL (optional)

10B Salience and Context Budget​

  • CRUVERO_SALIENCE_ENABLED (default true)
  • CRUVERO_MEMORY_SALIENCE_RELEVANCE (default 0.4)
  • CRUVERO_MEMORY_SALIENCE_RECENCY (default 0.3)
  • CRUVERO_MEMORY_SALIENCE_CONFIDENCE (default 0.2)
  • CRUVERO_MEMORY_SALIENCE_USAGE (default 0.1)
  • CRUVERO_MEMORY_SALIENCE_FRESHNESS (default 0.0)
  • CRUVERO_MEMORY_SALIENCE_HALFLIFE (default 24h)
  • CRUVERO_CONTEXT_BUDGET_ENABLED (default false)
  • CRUVERO_CONTEXT_BUDGET_TOKENS (default 8000)
  • CRUVERO_CONTEXT_SYSTEM_TOKENS (default 1000)

10C Temporal Reasoning​

  • CRUVERO_TEMPORAL_REASONING_ENABLED (default false)
  • CRUVERO_DEFAULT_FAST_MODEL (optional)
  • CRUVERO_DEADLINE_ACTION (default escalate, allowed escalate|halt)

10D Agent Immune System​

  • CRUVERO_IMMUNE_ENABLED (default false)
  • CRUVERO_IMMUNE_QUARANTINE_THRESHOLD (default 5)
  • CRUVERO_IMMUNE_QUARANTINE_TTL (default 0s)
  • CRUVERO_IMMUNE_CLEANUP_ENABLED (default true)
  • CRUVERO_IMMUNE_CLEANUP_INTERVAL (default 24h)
  • CRUVERO_IMMUNE_RETENTION_DAYS (default 90)
  • CRUVERO_IMMUNE_TOOL_THRESHOLDS (optional CSV tool:threshold)
  • CRUVERO_IMMUNE_TOOL_NO_AUTO (optional CSV tool list)
  • CRUVERO_IMMUNE_ALERT_ENABLED (default true)
  • CRUVERO_IMMUNE_ALERT_INTERVAL (default 5m)
  • CRUVERO_IMMUNE_ALERT_ANOMALY_DELTA (default 20)
  • CRUVERO_IMMUNE_ALERT_QUARANTINE_DELTA (default 3)
  • CRUVERO_IMMUNE_ALERT_BLOCKED_DELTA (default 10)
  • CRUVERO_IMMUNE_SNAPSHOT_ENABLED (default true)
  • CRUVERO_IMMUNE_SNAPSHOT_DIR (default backups/immune)
  • CRUVERO_IMMUNE_SNAPSHOT_BATCH (default 1000)

10E Compositional Tools and Contracts​

  • CRUVERO_COMPOSITE_MAX_DEPTH (default 8)
  • CRUVERO_COMPOSITE_MAX_STEPS (default 64)
  • CRUVERO_TOOL_CONTRACT_POSTCONDITION_MODE (default enforce, allowed enforce|warn)

10F Trust-Based Delegation​

  • CRUVERO_TRUST_ENABLED (default false)
  • CRUVERO_TRUST_REVIEW_THRESHOLD (default 0.3)
  • CRUVERO_TRUST_WEIGHT_SUCCESS (default 0.5)
  • CRUVERO_TRUST_WEIGHT_QUALITY (default 0.3)
  • CRUVERO_TRUST_WEIGHT_RECENCY (default 0.2)
  • CRUVERO_TRUST_RECENCY_DECAY (default 0.1)

10G Provenance Graph​

  • CRUVERO_PROVENANCE_ENABLED (default false)

Phase 10 Rollout Guide​

Use staged enablement so each capability can be validated independently and rolled back quickly.

Stage 0: Baseline Validation​

  • Keep all optional Phase 10 flags disabled (10A, 10C, 10D, 10F, 10G).
  • Run:
    • go test ./...
    • go test -tags integration ./internal/agent ./internal/supervisor -count=1
  • Confirm worker startup is clean with defaults.

Stage 1: Cognitive Features​

  • Enable:
    • CRUVERO_METACOGNITIVE_ENABLED=true
    • CRUVERO_SALIENCE_ENABLED=true (default)
    • CRUVERO_CONTEXT_BUDGET_ENABLED=true
    • CRUVERO_TEMPORAL_REASONING_ENABLED=true
  • Keep CRUVERO_IMMUNE_ENABLED=false, CRUVERO_TRUST_ENABLED=false, CRUVERO_PROVENANCE_ENABLED=false.
  • Validate prompt quality/latency and verify no unexpected escalation loops.

Stage 2: Runtime Safety​

  • Enable:
    • CRUVERO_IMMUNE_ENABLED=true
  • Keep trust/provenance disabled initially.
  • Validate anomaly, quarantine, and cleanup behavior in staging before production.

Stage 3: Delegation Policy​

  • Enable:
    • CRUVERO_TRUST_ENABLED=true
  • Set policy knobs explicitly:
    • CRUVERO_TRUST_REVIEW_THRESHOLD
    • CRUVERO_TRUST_WEIGHT_SUCCESS
    • CRUVERO_TRUST_WEIGHT_QUALITY
    • CRUVERO_TRUST_WEIGHT_RECENCY
    • CRUVERO_TRUST_RECENCY_DECAY
  • Validate trust score drift and reviewer fallback rates.

Stage 4: Provenance and Forensics​

  • Enable:
    • CRUVERO_PROVENANCE_ENABLED=true
  • Validate provenance node/edge persistence, subgraph retrieval, and run-diff behavior.

Rollback Order​

  • Disable in reverse order to minimize operational risk:
    1. CRUVERO_PROVENANCE_ENABLED=false
    2. CRUVERO_TRUST_ENABLED=false
    3. CRUVERO_IMMUNE_ENABLED=false
    4. CRUVERO_TEMPORAL_REASONING_ENABLED=false
    5. CRUVERO_CONTEXT_BUDGET_ENABLED=false
    6. CRUVERO_METACOGNITIVE_ENABLED=false

Temporal TLS​

  • If TLS enabled and address ends with :443, uses system CA (no mTLS).

Templates​

  • Agent scaffold includes .env.example and docker-compose.override.yml.