# Why CLIO Coder, part 1 of 5: your models, your machines

https://akougkas.io/journal/2026/why-clio-coder-1-your-models-your-machines/

Author: Anthony Kougkas

Published: 2026-09-20

Most coding agents answer the question of where your code goes before you have asked it. [CLIO Coder](https://akougkas.io/work/clio-coder/), the terminal coding agent I create and maintain inside [CLIO](https://akougkas.io/work/clio/), answers it the other way: every turn resolves through a model service you named, and there is no hosted model underneath it waiting to take over. With nothing configured the resolver returns `no targets configured; add one with clio-coder configure or clio-coder targets add` and the session does not start.

That refusal is the design, not a rough edge. A scientist with code under an export restriction, a lab with a gateway allocation, and an engineer with one GPU under the desk all need the same guarantee, and a silent failover to somebody’s API would void it for all three.

## One harness, many runtimes

A saved model service is a **target**: a runtime id, an endpoint, a model id, and whatever credentials the endpoint wants. Chat, workers, and optional model-assisted memory each resolve through a target, and they need not resolve through the same one. Configuration is target-first, which means the harness has no provider-specific flags that route around `settings.yaml`.

Four families of target ship in the tree. On your own workstation or server, the local runtimes cover llama.cpp, Ollama, LM Studio, vLLM, SGLang, and Lemonade. Through a gateway or a compatible API, LiteLLM and the generic OpenAI-compatible and Anthropic-compatible runtimes reach anything speaking those two protocols. As cloud APIs, OpenAI, Anthropic, Google, OpenRouter, Groq, Mistral, DeepSeek, and Amazon Bedrock each have a descriptor. By subscription sign-in, a ChatGPT plan connects through `openai-codex` and a Claude plan through `anthropic-max`, so an account you already pay for is a route rather than a second bill.

Institutional inference, reached through the gateway family, is the reason the list is not just a compatibility table. [Argonne](https://www.anl.gov/)’s [ALCF](https://www.alcf.anl.gov/) inference gateway is an OpenAI-compatible target backed by Globus OAuth, with `clio-coder auth login alcf` opening an authorize URL and asking you to paste the displayed code back. That flow was chosen because it survives SSH: a researcher on a login node with no browser can still authenticate. Sophia and Metis are configured as separate cluster targets, and Clio sends the configured wire model id literally rather than rewriting it, because a gateway’s model names belong to the gateway.

Diagram: Four families of model service feed one saved target: local servers such as llama.cpp, Ollama and vLLM; the ALCF inference gateway reached through Globus; cloud APIs such as OpenAI, Anthropic and Groq; and a Claude or ChatGPT subscription plan. The target resolves into one Clio harness, which produces one receipt.

Four families of model service feeding one saved target, which resolves into one harness and one receipt.

## Why a small model is worth pointing at

Choice of model is worth little if only a frontier model can drive the agent. Three properties of the harness are what let a model small enough to fit on a single workstation GPU do useful work, and each gets a part of this series to itself.

The agent never receives a raw shell as its general-purpose escape hatch. Tools are typed, and a turn’s constraints are shared between admission and prompt guidance so that ordinary English is not treated as an authorization parser. A weaker model produces malformed calls more often, and a typed boundary turns those into rejections instead of damage. Part 2 takes that apart.

Context is accounted for rather than hoped about. Since v0.5.2, input plus reserved output is enforced at submission, at settled tool continuation, and at the final provider boundary, and the live budget is inspectable through `/context`. When a handoff is needed the agent writes its own note, preserved exactly as it authored it. Part 3 follows that mechanism.

Every run seals a receipt. Tool activity, usage, traces, decisions, evidence, and worker results are recorded, which is what converts a cheap second opinion from a claim into a lead you can check. Part 4 covers bounded workers and what their receipts do and do not establish.

None of that makes a small model correct. It bounds what a wrong answer can cost and leaves a record of what was attempted, which is a different and more achievable promise.

## What v0.5.0 put in public

CLIO Coder reached v0.5.0 on September 20, 2026, and I wrote separately about [what made “public” the right word](https://akougkas.io/journal/2026/shipping-a-coding-agent-in-public/). For the provider layer the launch changed two things a newcomer meets first. The README was rewritten for a first-time reader and reviewed against the implementation, so the commands on the front page describe the build that ships. And `clio-coder configure` opens a launcher whose **Quick Connect** path takes an endpoint, credentials if the endpoint needs them, and a model selection, then shows you the connection before saving it. LM Studio commonly listens at `localhost:1234` and Ollama at `localhost:11434`; subscription sign-in lives under Settings → Connections.

The same release bundled a local browser application. `clio-coder gui` starts a server bound to 127.0.0.1 and prints a private launch link, and `clio-coder docs` opens the shipped documentation inside it and returns control to the terminal. Both read the same configuration, sessions, traces, and evidence as the command line. The documentation ships with the package, so asking Clio how to use Clio consults the version you are running instead of a guess. The launch notes call the terminal the primary coding interface and the wider application an early preview, and the GUI reference calls it a companion to the terminal agent. Clio is pre-1.0 and experimental by design; interfaces can move between minor versions.

The provider layer has kept moving since. On September 22, 2026 an `inception` runtime landed for Inception’s Mercury diffusion language models, authenticated from `INCEPTION_API_KEY`, with `mercury-2.5`, `mercury-2`, and `mercury-edit-2` as its known wire models. A diffusion model denoises whole blocks of tokens in parallel instead of emitting them left to right, which is what makes it fast enough for a latency-sensitive slot a frontier model cannot fill. Two surfaces are wired: chat at `/v1/chat/completions` with tool calling and JSON-schema structured outputs, and fill-in-the-middle at `/v1/fim/completions` through the same `infill()` verb that reaches llama.cpp’s. Mercury Edit 2’s next-edit prediction is deliberately left out, because it needs a contract verb of its own and its request format is not covered by the published reference. The runtime shipped in v0.5.3; no rates ship with it, and cost accounting reads the target’s own pricing block as it does for any other target.

Three model families with three different physics, one socket. That is the shape the provider layer is built to hold.

## Try it

You need Node.js 22.19 or newer and a model service. Install the package and configure a first target:

```
npm install -g @iowarp/clio-coder
cd /path/to/your/project
clio-coder configure
```

Choose **Quick Connect**, paste your endpoint, select a model, and review the connection. Then start a session, or check the installation first:

```
clio-coder doctor
clio-coder
```

Ask for something bounded on the first turn, such as an explanation of how the repository builds and tests itself. When you want the same view in a browser, open the companion:

```
clio-coder gui --open
clio-coder docs safety
```

You will see the terminal conversation, tool activity, and diffs in one place, and the browser application serving the same configuration, sessions, traces, and evidence from 127.0.0.1. For a longer walk through a local server, the [GPU tutorial](https://akougkas.io/journal/2026/clio-coder-on-your-own-gpu/) covers runtime ids, quantization, and reading the receipt.

## What is left for you

The provider list is long and the tested list is shorter. A model family counts as sanctioned only when the exact artifact, quantization, runtime surface, hardware, context window, and observed quirks are written down, and most of what people actually run has never been through that. If you connect Clio to a local server, a gateway, or a model nobody here has exercised, the useful artifact is that record: what you ran, where it was served, what the tool calls did, and where it failed. A difficult build, an unreliable connection, or a workflow that needs too much babysitting is equally worth reporting. Bring it to [the repository](https://github.com/iowarp/clio-coder), with your Clio and Node versions and `clio-coder doctor` output, credentials removed.
