Quickstart

Install Olyx before continuing. Choose Hugging Face or OpenAI below. For a provider-account-free workflow, use the local-server option below. See Providers for Hugging Face and other compatible endpoints.

Run commands from the same project directory. Database paths resolve beside the configuration file.

Choose a Connection

Connection	Prerequisite	Where to start
OpenAI	An available model and OPENAI_API_KEY	The walkthrough below
Local compatible server	A running server and installed model; no provider account	Local model setup
Hugging Face	HF_TOKEN and a model served by its router	Provider setup
Account-free fixture	Python 3 and a CLI source checkout	Testing guide
Custom adapter	An installed executable implementing the plugin contract	Creating a plugin

1. Configure a provider

Choose one setup in a new project directory. Both generate olyx.json and request.json with a fast alias.

Hugging Face

Use a model available through Hugging Face’s Inference Providers router. Replace YOUR_HF_MODEL_ID with its served model identifier:

export HF_TOKEN=your-hugging-face-token
olyx init --provider huggingface --model YOUR_HF_MODEL_ID
olyx check olyx.json

Olyx sends compatible Chat Completions requests to https://router.huggingface.co/v1 using HF_TOKEN. A downloaded Transformers model or an arbitrary Hub repository is not automatically a served endpoint. For a locally loaded model, use the local-server option or a provider plugin.

OpenAI

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

Configuration and credentials

init writes olyx.json and a sample request.json without overwriting existing files. The configuration defines the fast model alias. Credentials remain in environment variables. Use --model MODEL to select a model available to your account.

2. Send a request

olyx route --input request.json

The response includes the model output and a trace_id. Olyx creates data/traces.db beside the configuration and records the request locally.

3. Inspect the trace

Replace TRACE_ID with the returned identifier:

olyx debug TRACE_ID

Debug shows inputs, outputs, attempted models, fallback errors, and latency.

4. Replay the request

olyx replay TRACE_ID

Replay sends a new request

Replay makes a new provider call and preserves the original trace. Provider usage and charges apply to the new request.

To compare models, configure additional aliases and use olyx replay TRACE_ID --compare ALIAS1,ALIAS2. See Replay for examples.

Use a local model without a provider account

Start a local server that implements OpenAI-compatible Chat Completions, and select a model already installed in that server. Olyx does not install model weights or start the model server. For a server listening on port 11434, save this separate configuration as local.json, replacing YOUR_LOCAL_MODEL:

{
  "models": {
    "local": [{
      "base_url": "http://127.0.0.1:11434/v1",
      "model": "YOUR_LOCAL_MODEL"
    }]
  }
}

Save a request as local-request.json:

{
  "model": "local",
  "messages": [{"role": "user", "content": "Hello"}]
}

olyx check local.json
olyx route --config local.json --input local-request.json

Loopback HTTP routes can omit api_key_env. Use the returned trace ID with olyx debug TRACE_ID --config local.json or replay using the same configuration. For an application, olyx serve --local --config local.json starts the loopback endpoint. Model-server capabilities still determine whether streaming, tools, or embeddings work.

To exercise the CLI without a model server or provider account, run the account-free test suite from a source checkout. Its echo plugin is a fixture, not an inference model.

Next steps

• Connect an application with olyx serve; use serve --local to restrict binding to loopback.
• Configure providers and ordered fallbacks.
• Build a provider plugin without changing the CLI core.
• Run account-free tests and distinguish contract coverage from live verification.
• Stream responses from the terminal or application endpoint.
• Configure storage, retention, and backups.

Commands use ./olyx.json by default. Set OLYX_CONFIG or pass --config FILE for another path. See Configuration for fields and defaults.