Configuration

Spectron has two configuration surfaces: server-wide settings (in the server binary or environment) and per-Context configuration (stored in the control plane and patchable at runtime).

Server-wide configuration

Server configuration is provided via environment variables or a TOML configuration file passed at startup. These settings apply to all Contexts unless overridden at the Context level.

Core settings

Default model settings

These apply to all Contexts that do not override them:

The embedding model is fixed per deployment for launch — it is not a per-Context override. Context config rejects any models.embedding value other than the deployment default. Changing the server embedding model requires a reindex so vectors and HNSW indexes stay in the same embedding space.

Reranker (optional)

Cross-encoder reranking for /documents/query when use_reranker=true:

Multimodal providers (optional)

HTTP OCR, CLIP, and speech-to-text for document ingestion (read by the worker role). An HTTP provider takes precedence over the built-in local fallback for the same modality. Misconfigured URLs fail at boot.

See Multimodal content.

Default provider API keys

Object store configuration

CORS (browser clients)

Cross-origin browser calls to the API are off by default. Enable an origin allowlist when a web client (for example Surrealist against a Cloud-brokered access token) calls the user API from a different origin than the API host.

Comma-separated origins. Entries are trimmed, lower-cased, and normalised (trailing / stripped). Exact entries match the Origin header verbatim; entries containing * are anchored globs on both sides (bare * or https://* are rejected). Allowed origins are echoed in Access-Control-Allow-Origin; credentials are not used — callers authenticate with Authorization, not cookies. Preflight mirrors request headers so SDK headers (api-version, X-Spectron-Context, Idempotency-Key, and others) pass without a fixed allowlist.

The management API is normally server-side only; CORS is optional there for operator tooling.

Per-Context configuration

Each Context stores a config object in the control plane. This is updated via PATCH /api/v1/contexts/{id} and applies immediately to new requests.

Full config schema

{
  "config": {
    "token_limit": 1000000,
    "retention_days": 90,
    "models": {
      "extraction": "openai/gpt-4o-mini",
      "extraction_strong": "openai/gpt-4o",
      "query_understanding": "openai/gpt-4o-mini",
      "response": "openai/gpt-4o-mini",
      "reflection": "openai/gpt-4o",
      "background": "openai/gpt-4o-mini"
    },
    "providers": {
      "openai": "sk-...",
      "anthropic": "sk-ant-..."
    }
  }
}

Config fields

Provider API key visibility

Provider API keys are write-only on the API surface. The read projection for a Context replaces the key values with a providers_configured summary — names of providers for which this Context stores its own key:

{
  "config": {
    "providers_configured": ["openai", "anthropic"]
  }
}

This is not the same as GET /api/v1/{context_id}/providers, which lists providers reachable via a global deployment key or a per-Context key and includes selectable model ids. The two surfaces are not derivable from each other.

The raw key values never appear in read responses.

Patching config

Send only the fields you want to change. Unset fields are left unchanged (deep merge):

PATCH /api/v1/contexts/acme-prod
Content-Type: application/json
Authorization: Bearer mgmt-...

{
  "config": {
    "token_limit": 2000000,
    "models": {
      "reflection": "anthropic/claude-opus-4-7"
    }
  }
}

Extraction tuning

Additional per-Context settings control extraction behaviour:

Cache settings

Rate limiting

Key policy

Every data-plane API key must be bound to a principal. Keys with no principal binding are rejected with 401 — there is no unscoped passthrough mode. Mint keys under a principal (management API or self-service POST /{ctx}/keys).

Request and list limits

Operator-tunable ceilings (env vars, read at process start):

Requests above the query ceiling return 400 Bad Request.

Reconciliation

Defaults reference

When a per-Context field is not set, the server-wide default applies. The effective configuration for a Context is always visible at:

GET /api/v1/contexts/{id}

The response includes the config object with all effective values merged – Context-level overrides where set, server-wide defaults elsewhere.