Ivy: User Manual

Ivy is an AI coding agent with two modes. By default it runs against hosted models through the Fight Club platform, exactly as Knockout does. With --local it runs the same agent against a model on your own machine or LAN, with no account and no platform.

This manual covers local mode. Hosted mode is Knockout with a different name on the binary; the Knockout manual at knockout.fightclub.pro/manual applies to it in full.

1. What local mode is

ivy --local is the Knockout agent with the platform removed. Same tool loop (read, write, edit, run shell commands, search), same terminal UI, same permission prompts, but every model call goes to an OpenAI-compatible endpoint you name, and nothing else is contacted.

Concretely, local mode:

• runs the full agent pipeline in-process on your machine;
• ships the coding guardrails and the pipelines baked into the binary, so it never fetches anything from a server to start;
• makes no call to fightclub.pro or any Knockout service. The only outbound connection it opens on its own is to your endpoint.

One honest exception. The agent's WebFetch and WebSearch tools work in local mode when the model decides to use them. On an air-gapped box they fail and the agent carries on; they are not blocked by the binary.

What local mode does not have, because these are platform services: the worker fleet and parallel execution, cross-device memory sync, RAG stores and the Brain, the skills registry, billing, MCP serving for IDEs and the update check. Section 10 lists the gaps in full.

2. Who it's for

Two groups.

Anyone with a decent GPU who is tired of paying per token. A 32B coder model from Hugging Face on a single card, served by Ollama, drives Ivy well enough for most day to day work. The card you already own does the inference.

Organisations that cannot let code or prompts leave their network. Data residency, ISO 27001, a real air gap. The typical setup is a GPU box on the LAN serving a model through vLLM, and developers running ivy --endpoint http://that-box:8000/v1 on their workstations.

3. Requirements

An OpenAI-compatible endpoint that exposes /v1/chat/completions, served by a model that supports OpenAI-style tool calling.

Runtimes that work:

• Ollama (quickest start on a laptop; raise its context first, see section 8)
• vLLM (the right choice for a GPU box; needs --enable-auto-tool-choice and a tool parser)
• llama.cpp server
• LM Studio
• Text Generation Inference (TGI)
• SGLang
• NIM containers

Tool calling is the hard requirement. The whole pipeline is tool driven: the agent works by calling Read, Write, Edit, Bash, Glob and Grep. A model or runtime that only returns text cannot drive the loop however capable it is at prose. A base model served without a tool-calling template emits its calls as text and the loop stalls. Run ivy doctor before you trust an endpoint.

4. Install

curl -fsSL https://ivy.fightclub.pro/install.sh | sh

Windows, in PowerShell:

irm https://ivy.fightclub.pro/install.ps1 | iex

Binaries are published for Linux, macOS and Windows on amd64, arm64 and a few smaller targets, with checksums.txt next to every release at https://ivy.fightclub.pro/releases/<version>/. For an air-gapped machine, download the binary and the manifest on a connected one, verify the SHA-256, and copy it across. ivy update checks ivy.fightclub.pro for a newer version; that is the one call Ivy makes on its own account, and only when you run that command.

To build from source:

cd ivy-cli
go build -o ivy .

5. Quickstart

Run doctor first. It checks two things: that the endpoint speaks OpenAI-compatible chat completions, and that the model returns a real tool call rather than describing one. That single check catches the most common failure before you blame the agent.

ivy doctor --model qwen2.5-coder:32b

With no --endpoint, doctor and local mode assume Ollama at http://localhost:11434/v1. On success:

✓ qwen2.5-coder:32b: drives tools (Write) via native tool_calls

If the model only produces tool calls as text and Ivy's fallback recovered them, the line says so. If it cannot drive tools at all, doctor fails and tells you to use a stronger model or one served with a proper tool-calling template.

Then work:

cd your-project
ivy --local --model qwen2.5-coder:32b

That opens the interactive terminal. For a single task with no terminal:

ivy --local --model qwen2.5-coder:32b --print "fix the failing test"

By default Ivy asks before running any tool that is not already allowed (Read, Glob, Grep and basic shell commands are allowed out of the box). --npa approves everything without asking, for headless or CI runs.

6. Command reference

ivy [flags] [prompt]
ivy doctor [flags]
ivy --local --attach <id>

Flags come first, then environment variables, then defaults.

The model id

The --model value goes to your endpoint exactly as typed. It is the literal id the runtime serves, not an alias. Find it with:

curl http://localhost:11434/v1/models

and use the id field.

Several models

ivy --local --model qwen2.5-coder:32b,deepseek-coder-v2

The first model is the primary. It runs every step that runs one model, and it judges the steps that run several. The rest are extra candidates on the steps the pipeline already runs several models on, which today means the Plan step of the full pipeline. In the simple pipeline only the primary runs. Inside the terminal, /model moves a different model to the front.

Detached tasks

ivy --local --model qwen2.5-coder:32b --detach "migrate the tests to testify"

The task runs in a separate process. Ctrl-C leaves it running; ivy --local --attach <id> streams it again, or replays it from the log once it has finished. A detached task approves every tool call itself, since nobody is at the terminal to answer, and it does not write a resumable session.

Sessions

Local sessions are saved to <cwd>/.ivy/sessions/<id>.json after every turn, in plain text. -c continues the most recent one, -r shows a picker and --resume-id names one. A resumed session supplies its model list if you do not pass one.

7. Pipelines

Two pipelines are baked into the binary.

simple is the default. One step, a straight tool loop, no handoff between stages. It is the reliable choice on smaller models, which is why it is the default: a multi-stage pipeline loops or stalls when the model cannot reliably emit structured tool calls. Start here.

full is Knockout's standard pipeline: plan, then act, then verify. Use it with a strong model. Its Plan step is where a list of models becomes several candidates and a judge. On a weak model it can do worse than simple, so move to it once simple is solid on your setup. Switch inside the terminal with /pipeline.

8. Models and the Ollama context trap

Prefer a model with native tool calling. Using the Qwen family as the example, qwen3 emits native tool_calls while qwen2.5-coder tends to put its calls in the text. Both work (section 9 covers the fallback), but native is the cleaner path.

Ollama's default context is 4096

Read this before anything else if you serve with Ollama. Every model gets num_ctx=4096 unless told otherwise. The agent's system prompt and tool definitions come to roughly 6,500 tokens. At 4096, Ollama silently truncates that, part of the tool contract is lost, and the model starts improvising. The symptom is a model that behaved in chat but ignores its tools or invents results under Ivy.

Raise the context. Either derive a model:

FROM qwen3:8b
PARAMETER num_ctx 32768

ollama create qwen3-32k -f Modelfile
ivy --local --model qwen3-32k

Or set it on the server:

OLLAMA_CONTEXT_LENGTH=32768 ollama serve

32k is ample. Larger does not help and costs memory.

Cold starts

The first request after Ollama or vLLM loads a model can take a minute while the weights go into VRAM. Ivy waits up to five minutes for the first response header in local mode, so a cold model is not mistaken for a dead endpoint.

GPU boxes: vLLM

For a real GPU server, serve with vLLM, --enable-auto-tool-choice and the right --tool-call-parser (hermes for Qwen, llama3_json for Llama 3.x, mistral for Mistral). vLLM serves the full native context and clean tool calling, so Ivy's rescues stay inert and behaviour matches the hosted pipeline. vLLM is CUDA-first; on a Mac, Ollama with a raised context is the path.

9. How Ivy copes with weaker models

Ivy carries four rescues for models that are weak or badly served. All of them are inert on a strong, well-served model.

Content to tool-call fallback. Some models return a tool call as text inside the message, sometimes fenced, sometimes wrapped in <tool_call> tags, instead of a structured tool_calls field. Ivy scans the content, extracts the call and synthesises the structured one, in both the streaming and non-streaming paths.

Emit gating. Weaker models call the "done" tool on the first turn and fabricate a finished result without doing any work. Ivy withholds every completion tool until a real tool result exists in the history, and forces a genuine tool call on the first turn. A request that needs no file change still terminates cleanly.

The anti-lie retry. When a turn attempted file edits and none of them landed, Ivy appends a corrective message telling the model to read the file and write it properly, and runs the turn again, up to twice. The retry is visible in the transcript.

Whitespace-tolerant Edit. A weak model often reproduces a snippet with its indentation slightly off. When an exact match fails, Ivy matches ignoring surrounding whitespace, splices using the file's real bytes, and only when the match is unique. An ambiguous match is refused with a hint to include more lines.

doctor reports which of these did the work on the probe, so you know what you are relying on.

10. What local mode does not do

• No per-step model tiering. Hosted mode picks a model size per step from a catalogue; local mode has no catalogue, so a step runs the model you named. A model list is the tiering you get (section 6).
• No memory sync across devices, no RAG stores, no Brain, no episodic memory. Local memory files under .ivy/memory work as normal and stay on the machine.
• No worker fleet, no parallel subagents.
• No skills registry. Skills you create locally load as normal.
• No MCP serving for IDEs.
• No billing, wallet or cost display. Your endpoint is unmetered by Ivy.
• No automatic update check. ivy update is on demand.
• Web tools are not blocked (section 1).
• Prompt caching is off; it is an Anthropic-native feature and does nothing on a self-hosted endpoint.

11. Security and data residency

Your key stays on your box. If your endpoint needs one, it lives in --api-key or IVY_API_KEY on your machine and is sent only to your endpoint. There is no vault, no lease, no handshake with anything of ours.

Data residency. Your prompt, your code, tool output and the model's completions travel only between your working directory and your endpoint, with the WebFetch and WebSearch caveat from section 1.

Local files. Sessions, memory and edit snapshots live under <cwd>/.ivy, in plain text, with owner-only permissions. Settings live in ~/.ivy/settings.json. Both ~/.ivy and ~/.ko are on the tool sandbox's denylist, so the agent cannot read or write them.

Tool sandbox. Same executor as Knockout: the bash allow and deny rules, the path guards, the confinement to the project tree. Missing settings yield safe defaults without Ivy writing any files. Untrusted project-level .ivy settings are stripped.

Attribution. Local mode sends no platform brand to your endpoint; the request carries only what the OpenAI chat API needs plus any header you add.

12. Troubleshooting

doctor fails with "the model neither emitted a tool call nor a parseable one in its content". The model or runtime is not doing tool calling. It does not support it, or it is served without a tool-calling template, or on Ollama its context is truncating the tool contract. Switch model, serve with the right template, and on Ollama raise num_ctx (section 8).

doctor fails with "timeout awaiting response headers". The model was still loading. Run it again; the first request after a load can take a minute. If it keeps happening, the endpoint is not answering at all.

The model says it did the work but the files are unchanged. Classic weak-model or truncated-context behaviour. On Ollama, raise num_ctx first. If it persists, move to a stronger model or to vLLM. The anti-lie retry catches the blatant version; a badly truncated model can still underperform.

Connection refused. Wrong endpoint or port, or the runtime is not up. curl <endpoint>/models should answer before you try Ivy.

404, model not found. The --model id does not match what the endpoint serves. Copy the exact id from curl <endpoint>/models.

13. FAQ

Does my data leave my network? In local mode the only connection Ivy opens is to your endpoint, plus the web tools if the agent uses them. No account, no telemetry, no platform.

Do I need an API key? Only if your endpoint requires one. Leave --api-key empty otherwise.

Which model should I use? One with real tool calling. On a GPU box, vLLM with --enable-auto-tool-choice. On a laptop, qwen3 or qwen2.5-coder on Ollama with the context raised to 32k. Run doctor.

Can I mix modes? Yes. ivy with no flag is hosted; ivy --local is local. Same binary, same settings, separate session stores.

Can it run fully offline? Yes, apart from the web tools, which fail harmlessly. Copy a verified binary across, point it at an endpoint on the LAN, and run.