Connect a model
CLIO does not ship a model. It connects to one you already have: a model running on your machine, a cloud API, or a subscription you pay for. You choose the provider once, and you can change it at any time.
Choose a provider in the app
Section titled “Choose a provider in the app”The first time an interface connects to the backend, CLIO asks you to choose a provider. Pick one, fill in what it asks for (an API key, a base URL, or nothing), and save.
To change it later:
- In the terminal UI, press Ctrl+S to open Settings, choose Model, then choose Change provider.
- In the desktop app and the web UI, open the model settings and choose a provider from the list.
CLIO discovers the available models from the provider when it can. You can also type a model id yourself. CLIO has no built-in model list to go stale.
Providers
Section titled “Providers”CLIO supports 16 providers.
On your machine
Section titled “On your machine”These run on your own hardware. Nothing about your prompts leaves the computer. Start the server before you connect.
| Provider | What it needs | Default address |
|---|---|---|
| LM Studio | The LM Studio local server running, with a model loaded | http://127.0.0.1:1234/v1 |
| Ollama | Ollama running | http://127.0.0.1:11434 |
| llama.cpp server | A llama.cpp server running | http://127.0.0.1:8088/v1 |
| vLLM | A vLLM server running | http://127.0.0.1:8000/v1 |
Leave the model empty and CLIO uses the model the server reports as loaded. If your server listens on a different port or machine, change the base URL.
Cloud APIs
Section titled “Cloud APIs”| Provider | What it needs |
|---|---|
| OpenAI API | An API key (OPENAI_API_KEY) |
| Anthropic API | An API key (ANTHROPIC_API_KEY) |
| Azure OpenAI | An API key (AZURE_API_KEY), your resource URL, and an API version |
| Google Gemini | An API key (GOOGLE_API_KEY) |
| Google Vertex AI | Google Cloud credentials already set up on the machine, a project, and a location |
| AWS Bedrock | AWS credentials already set up on the machine, and a region (a profile name is optional) |
| NVIDIA NIM | An API key (NVIDIA_NIM_API_KEY) |
| OpenRouter | An API key (OPENROUTER_API_KEY) |
For Vertex AI and Bedrock, CLIO uses the credentials your machine already has (Google Application Default Credentials and the AWS credential chain). You do not paste a key.
Subscriptions
Section titled “Subscriptions”| Provider | What it needs |
|---|---|
| Codex | Sign in with your ChatGPT or Codex account. Usage counts against your Codex plan. |
| Claude Code | A Claude Code subscription, signed in once on this machine. CLIO can start the sign-in from the provider settings, or run claude auth login in a terminal. |
Research computing
Section titled “Research computing”| Provider | What it needs |
|---|---|
| ALCF Sophia | A Globus sign-in with your ALCF or Argonne identity |
| ALCF Metis | The same Globus sign-in as Sophia |
Notes for specific providers
Section titled “Notes for specific providers”LM Studio and Ollama
Section titled “LM Studio and Ollama”Start the local server first. In LM Studio, load a model and start its server. In Ollama, make sure the Ollama service is running and you have pulled a model.
Claude Code
Section titled “Claude Code”Check that claude --version works in a terminal, then sign in once: CLIO offers this in the provider settings, or run claude auth login in a terminal. CLIO uses your subscription through Claude Code, so no API key is needed.
Choose Codex and sign in with your account when prompted. CLIO calls Codex directly. You do not need the Codex command-line tool.
ALCF Sophia and Metis
Section titled “ALCF Sophia and Metis”CLIO signs in through Globus. Authenticate once per machine. The install script includes the support this needs. From a terminal, run the following using the Python in CLIO’s environment:
~/.local/share/clio/clio-agent/.venv/bin/python -m clio_agent.providers.argonne_auth authenticateOn Windows, use %LOCALAPPDATA%\clio\clio-agent\.venv\Scripts\python.exe in place of that path. Tokens refresh automatically afterward.
Environment variables
Section titled “Environment variables”For a headless server or a Docker container, set the provider before the backend starts.
| Variable | Meaning |
|---|---|
CLIO_LM_PROVIDER |
Provider id, such as lm_studio or openai (see the ids below) |
CLIO_LM_API_BASE |
Override the provider’s base URL |
CLIO_LM_MODEL |
The model id to use |
CLIO_LM_API_KEY |
A fallback API key |
Provider ids: lm_studio, ollama, llama_cpp, vllm, openai, anthropic, azure_openai, gemini, vertex_ai, bedrock, nvidia_nim, openrouter, codex, claude_code, argonne_sophia, argonne_metis.
CLIO_LM_PROVIDER=openai OPENAI_API_KEY=sk-... clio startConfiguration file
Section titled “Configuration file”You can also set the provider in config.yaml with the keys lm.provider, lm.api_base, and lm.model. A value in the file wins over the environment variable. API keys are never read from config files. See Configuration.
How API keys are stored
Section titled “How API keys are stored”When you save a key in the app, CLIO writes it to provider_api_keys.json in your user configuration folder, readable only by you. For each provider, CLIO looks for a key in this order:
- The key saved in the app.
- The provider’s own environment variable, such as
OPENAI_API_KEY. CLIO_LM_API_KEY.