akougkas.io

Run CLIO Coder against a model on your own GPU

Install CLIO Coder from npm, point it at a local llama.cpp or LM Studio server, run one headless turn, and read the receipt it seals.

Published
Updated
Reading
6 min read
Topics
agents, systems, scientific computing, building
Tested with
CLIO Coder 0.3.7
Current release
CLIO Coder v0.7.0, November 9, 2026
Tested on
Environment
Linux or macOS, a local llama.cpp or LM Studio server

A local turn

  1. Install

    Get the CLI from npm.

  2. Serve a model

    Start llama.cpp or LM Studio.

  3. Run a turn

    Configure a target, then run headless.

  4. Read the receipt

    Inspect what the session recorded.

The tutorial connects CLIO Coder to a local model server, runs one headless turn, and ends by inspecting the receipt.

September 27, 2026: This walkthrough retains its original tested CLIO Coder v0.3.7 instructions. Starting with 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 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 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, the context architecture I lead across 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. If a local model is useful here, it is because the harness around it does the work a model cannot do for itself.

Sources, code, and records

  1. source

    CLIO Coder README

    The source of every command in this tutorial.

  2. source

    Configuration and targets

    The full reference for runtimes, endpoints, fleet profiles, and auth.

  3. source

    Model catalog

    Quantizations, context windows, and quirks per model family.

  4. source

    @iowarp/clio-coder on npm

    The package this tutorial installs.

  5. source

    Run CLIO Coder on a local model

    The product tutorial for the same setup.

  • 2023–present
    active

    CLIO Coder

    A local-first coding agent with typed tools, bounded workers, and receipts

  • 2025–present
    active

    CLIO

    A context layer for scientific AI agents and workflows

More on CLIO Coder

  1. tutorial

    A closed loop for AI-assisted research writing

    Install CLIO Coder, WTF-P, and CiteNexus on Linux and run a first supervised writing session: the agent keeps the bookkeeping, every citation stays traceable to its source, and the author keeps the judgment.

    10 min
  2. tutorial

    Serving Qwen3.8-27B on a Radeon AI PRO R9700 is not a one-liner

    The same Qwen3.8-27B GGUF on the same 32 GB Radeon decodes at 27 or 46 tokens per second, and the difference is speculative decoding. The backend is a prefill and decode trade, KV precision is a memory choice, and this is the llama.cpp preset I run under CLIO Coder.

    18 min
  3. essay

    Reliable work from unreliable agents

    A coding agent is a system built around one brilliant, persuasive, unreliable component. The argument of my November 9, 2026 lecture on agentic engineering: five ideas for building trustworthy work around that component, what they could do for science, and the problems still open.

    14 min