Configuration reference

Olyx reads a JSON configuration file. Unknown fields are rejected. Route, replay, and debug default to ./olyx.json; OLYX_CONFIG and --config FILE select another file.

Minimal configuration

Save this as olyx.json. Replace the model identifier with one available to your provider account.

{
  "models": {
    "fast": [{
      "base_url": "https://api.openai.com/v1",
      "model": "gpt-4o-mini",
      "api_key_env": "OPENAI_API_KEY"
    }]
  }
}

export OPENAI_API_KEY=your-provider-key
olyx check olyx.json

Model routes are the only required top-level section. Storage defaults to data/traces.db beside the configuration file. SQLite is bundled and initialized automatically.

Top-level fields

Field	Type	Default	Description
models	Object	Required	Alias names mapped to nonempty ordered provider arrays
database	String	data/traces.db	SQLite path relative to the configuration directory, or :memory:
policy	Object	Defaults below	Optional local request validation and retention settings

Aliases are local names. The request’s model selects an alias; the provider entry’s model selects the actual upstream model.

Provider fields

Field	Type	Default	Description
protocol	String	openai	openai or plugin
base_url	String	HTTP only	Compatible HTTP base URL; omit for plugins
model	String	Required	Upstream model identifier
api_key_env	String	Remote HTTP only	Credential variable; optional for loopback HTTP and account-free plugins
plugin	Object	Plugin only	Executable, arguments, capabilities, environment allowlist, and timeout
embedding_response_models	String array	[]	Explicitly approved response identifiers for the same vector space
input_per_million, output_per_million	Number	0	Optional nonnegative cost telemetry; never affects routing

URLs must use HTTPS except for loopback HTTP endpoints. URLs cannot embed credentials, query parameters, or fragments. Provider credentials belong in the environment, not the JSON file. See provider protocols for compatible HTTP configuration and plugins.

Ordered fallbacks

{
  "models": {
    "fast": [
      {"base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY"},
      {"base_url": "http://127.0.0.1:8080/v1", "model": "YOUR_INSTALLED_LOCAL_MODEL"}
    ]
  }
}

Candidates are tried in array order for eligible failures. Fallback providers must accept the request format. All requests use common fields. Plugin candidates must declare support for the requested capabilities.

Request validation and retention

Field	Default	Validation
policy.max_body_bytes	262144 (256 KiB)	Positive integer, at most 8388608 (8 MiB)
policy.max_output_tokens	1024	Positive integer; chat generation request limits cannot exceed this value
policy.max_embedding_response_bytes	67108864 (64 MiB)	Positive integer up to 1 GiB; bounds buffered embedding responses
policy.retention_days	30	Positive integer; expiration runs when the runtime opens storage

{
  "policy": {
    "max_body_bytes": 1048576,
    "max_output_tokens": 4096,
    "retention_days": 90
  }
}

Merge this object into a complete configuration containing models. These settings validate requests and manage local retention; they do not scan or redact prompt content. Provider limits still apply.

Check and diagnose

olyx check olyx.json
olyx inspect --config olyx.json

Check validates syntax, route structure, URLs, and settings without requiring credentials. It does not call providers, confirm model access, or create the database. Configured credential values are checked when the corresponding route is used; credential-free local routes do not require a key. Check validates plugin settings without launching the executable or verifying its runtime capabilities.

Embedding aliases use the same provider array format. See Embeddings and RAG for model selection and replica fallback constraints.

Provider extensions

Use protocol: "plugin" with an absolute executable, explicit capabilities, and optional credential environment variable. See the versioned plugin contract. Loopback HTTP providers and credential-free plugins can omit api_key_env. Use common Chat Completions or embeddings request fields.

Plugin fields

Field	Required/default	Meaning
plugin.command	Required	Absolute executable path; no shell expansion
plugin.args	[]	Arguments passed directly to the executable
plugin.capabilities	Required	Nonempty subset of chat, streaming, tools, embeddings; streaming/tools also require chat
plugin.env	[]	Additional environment variable names explicitly allowed into the child
plugin.timeout_ms	60000	Total invocation timeout, from 100 through 300000 ms

A plugin route must omit base_url. Only explicitly configured executables run; plugins are not downloaded or discovered automatically. They are trusted local code, not sandboxed extensions. See Provider plugins for the versioned wire protocol, credential handling, and test fixtures.