Provider setup

Connect compatible endpoints, Hugging Face, local models, and independent provider plugins.

Olyx sends HTTP requests in the OpenAI-compatible format. Use OpenAI directly, Hugging Face’s compatible router for models in its catalog, or a local compatible server. Independent provider plugins can translate requests to other services. The core does not bundle native service SDKs or adapters.

Before continuing, install Olyx and choose a model available through the selected endpoint. Local servers must already be running; plugins must already be installed. olyx check validates configuration but does not verify a model’s availability or start an adapter.

Connection	Configuration	Credentials
OpenAI	protocol `openai`, `https://api.openai.com/v1`	OPENAI_API_KEY
Hugging Face router	protocol `openai`, `https://router.huggingface.co/v1`	HF_TOKEN
Local compatible server	protocol `openai`, loopback base URL	Optional
External executable	protocol `plugin`, explicit command and capabilities	Adapter-specific; optional

OpenAI

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

Set OPENAI_API_KEY before routing. Initialization writes aliases and a sample request without saving credentials. Choose a model available to your account.

Hugging Face

export HF_TOKEN=your-provider-token
olyx init --provider huggingface --model YOUR_HF_MODEL_ID
olyx check olyx.json
olyx route --input request.json

Set HF_TOKEN with permission to make Inference Providers calls. Choose a served model from the Hugging Face catalog, not an arbitrary model repository. A provider suffix in the Hugging Face model identifier, when supported, is preserved. Olyx sends Chat Completions JSON to the router; Hugging Face handles its downstream provider selection and translation. Only models/features available through that service are accessible. This does not imply access to Bedrock, Claude, or every model offered directly by a service. Availability, tools, images, token controls, and streaming depend on the selected routed model.

This route uses the same HTTP request code as OpenAI. Local tests check that code with simulated responses. Testing the Hugging Face service itself requires an HF_TOKEN and an available model. Hugging Face is an optional endpoint, not an Olyx dependency.

Local models without accounts

Start your compatible model server, then use examples/ollama.json, adjusting the model to one installed locally:

olyx check examples/ollama.json
olyx route --config examples/ollama.json --model local --input examples/request.json

The example uses http://127.0.0.1:11434/v1. Credential configuration may be omitted for loopback HTTP endpoints; remote endpoints require a configured credential variable. Olyx does not install or download local model weights. Use your model server’s instructions to start it and obtain a model.

Fallback and streaming

examples/fallbacks.json tries OpenAI and then Hugging Face for eligible failures. Set OPENAI_API_KEY and HF_TOKEN and replace the Hugging Face model placeholder. Only connection failures, 429, and 5xx responses trigger HTTP fallback. Invalid requests or credentials stop execution, and partial output never triggers a new provider. The model ID sent to Hugging Face is recorded as configured; provider selection internal to the router is not an Olyx provider attempt.

olyx route --config examples/fallbacks.json --input examples/request.json
olyx replay TRACE_ID --config examples/fallbacks.json --compare fast,huggingface
olyx debug TRACE_ID --config examples/fallbacks.json

Set stream: true for cumulative CLI snapshots or HTTP SSE through serve. Tools, image content, and supported generation options use standard Chat Completions fields directly. Embeddings require an OpenAI-compatible /embeddings endpoint or an embedding-capable plugin; Hugging Face chat routing does not establish embeddings compatibility.

Extend with a plugin

Adapter authors can develop and run the versioned plugin contract kit without provider accounts. Verification status and tests keep local contract coverage separate from live service compatibility.