# Run CLIO Coder against a model on your own GPU

https://akougkas.io/journal/2026/clio-coder-on-your-own-gpu/

Author: Anthony Kougkas

Published: 2026-08-26

Updated: 2026-08-27

**September 27, 2026:** This walkthrough retains its original tested CLIO Coder v0.3.7 instructions. Starting with [v0.5.6](https://github.com/iowarp/clio-coder/releases/tag/v0.5.6), the old autonomy names are rejected; `default` and `yolo` are the supported levels, and read-only is a separate dispatch restriction. Use the [current product guides](https://coder.iowarp.ai/docs.html) for a new installation. The full workflow below has not been retested against v0.5.7.

Most of the scientists I work with have exactly one GPU and code they cannot send to a cloud API. [CLIO Coder](https://akougkas.io/work/clio-coder/) was built for that room: a coding agent that runs against a model on your own hardware and seals a receipt you can read afterwards.

CLIO Coder treats a model as a named **target**: a runtime, an endpoint, a model id, and credentials. Everything below is documented in the v0.3.7 README and `--help`; I have only put it in the order I actually follow on a fresh machine.

## Prerequisites

- Node.js 22.19 or newer and npm.
- Linux or macOS. Windows is best effort until a stable release.
- A local inference server. Any of llama.cpp, Ollama, LM Studio, vLLM, or SGLang works; the runtime ids are `llamacpp`, `ollama-native`, `lmstudio`, `vllm`, and `sglang`.
- A model loaded in that server. If you have one GPU with 24 GB or more, the release was hardened against **Qwen3.8-27B** (the `unsloth/Qwen3.8-27B-GGUF` quantizations) on llama.cpp and LM Studio. A 4-bit quantization at 131072 context fits in 24 GB with a q8_0 KV cache.

Version as of August 26, 2026:

```
$ clio-coder --version
Clio Coder 0.3.7
```

## 1. Install

```
npm install -g @iowarp/clio-coder
clio-coder --version
```

From source instead, pinned to the release:

```
git clone --branch v0.3.7 https://github.com/iowarp/clio-coder.git
cd clio-coder
npm run install:local
export PATH="$HOME/.local/bin:$PATH"
hash -r
```

`npm run install:local` builds the CLI, links it at `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}/clio-coder`, and initializes the home directory. If an older install is on your `PATH`, `command -v clio-coder` shows which binary the bare name reaches.

## 2. Start the model server

For llama.cpp, start it with the flags the README asks for so tool calls and reasoning parse cleanly:

```
llama-server --jinja --reasoning on -m /path/to/Qwen3.8-27B-Q4_K_M.gguf -c 131072
```

LM Studio needs nothing beyond loading the model. Note the port your server listens on; 8080 is llama.cpp’s default and 1234 is LM Studio’s.

## 3. Configure a target

The interactive way:

```
clio-coder configure
```

The wizard lists runtimes, asks for the endpoint and model, probes it, and saves it as both the chat and worker target. Bare `clio-coder` opens the same wizard when nothing usable is configured.

The scripted way, which does the same thing without prompts:

```
clio-coder configure --id local-lmstudio --runtime lmstudio \
  --url http://localhost:1234 --model your-model-id \
  --set-orchestrator --set-fleet-default
clio-coder targets --probe
```

`clio-coder targets` prints every configured target with its tier, runtime, auth state, URL, model, health, and capability flags. `--probe` actually connects. The model id has to match what the server advertises: if LM Studio has a different model resident than the one in your target, the turn fails immediately with a message naming the resident instances instead of silently routing to whatever is loaded. That is deliberate.

## 4. Run one headless turn

From any repository:

```
clio-coder run "Summarize this repository layout and its entry points." --json
```

`--json` streams JSONL events: a `session` record with the session id, working directory, target, model, and Clio version; `agent_start`, `turn_start`, `message_start`, `message_end`, `turn_end`, and `agent_end`; and tool events in between when the model calls tools. The `agent_end` event carries measured usage (input, output, cache reads and writes, reasoning tokens, API calls, and cost in dollars). Add `--autonomy read-only` if you want the guarantee that nothing can be mutated or executed on this turn; every mutating call is denied and the denial is recorded.

To hand the same task to a fleet agent instead of the main loop:

```
clio-coder run "<task>" --agent coder
```

That run gets its own receipt.

## 5. Read the receipt

```
clio-coder evidence list
clio-coder evidence inspect <runId>
```

A receipt covers routing intent, the resolved route, worker attestation, priced cost, phase timing, tool activity, safety decisions, and result conformance. Inside an interactive session, `/view verify <runId>` shows the same thing. `clio-coder trace` reads the durable dispatch trace.

## 6. Go interactive

```
cd your-project
clio-coder context init     # drafts CLIO-CODER.md from the source tree
clio-coder
```

`context init` writes the project handbook Clio loads every session and can adopt an existing `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` with provenance. In the session, `/settings` changes the model or autonomy level, `/context` and `/cost` show what is in the window and what it costs, and `/help` lists the rest.

## Limitations

- CLIO Coder is experimental. Interfaces may change between minor versions, and model-specific behavior varies by target. Keep the repository under version control and review what it proposes.
- A local model’s usefulness depends on the quantization, the context length you can afford, and whether tool calls parse cleanly. The model catalog in the repository records what has been checked per family; other models may need `--jinja` or a different chat template.
- The receipt records what the harness observed. It does not make the model’s reasoning correct.
- Connecting a Claude or ChatGPT subscription over OAuth uses the same path as the vendors’ own tools; using subscription credentials outside a vendor’s first-party apps may not align with their terms. That is your call, not Clio’s.
- Windows is best effort.

If something in here does not match what you see, `clio-coder doctor` plus `clio-coder --version` and `node --version` is what I need in a bug report. Redact secrets and private prompts first.

## Where this fits

The receipt is the point. CLIO Coder is one hands-on surface inside [CLIO](https://akougkas.io/work/clio/), the context architecture I lead across [IOWarp](https://akougkas.io/work/iowarp/), and the same ideas about bounded selection, typed authority, and sealed evidence are what I argue for in [Context is part of the system](https://akougkas.io/journal/2026/context-is-part-of-the-system/). If a local model is useful here, it is because the harness around it does the work a model cannot do for itself.
