docs › Use a local model with Ollama

Use a local model with Ollama

Run the analyst, your agents and paper autotrade on a free model on your own machine, with no login and no key, behind a restriction profile you choose.

dexterm can run its AI on a model on your own computer through Ollama, instead of your Claude or Codex login. There is no account, no key and no bill: the model runs on your machine and every answer costs $0. dexterm talks to Ollama on http://127.0.0.1:11434 by default, so your questions, the screen context and the tool results stay on this machine.

A local engine can do everything the Claude path does: the analyst and its skills, tune-by-chat strategy proposals, the AUTOTRADE runner's sessions, and an agent on the dexterm tools. You decide how far it may go with a restriction profile. The limits that protect money are not part of that choice: they are enforced outside the model and are the same for every engine (see what stays outside the model).

Set it up in two minutes#

1. install Ollama            https://ollama.com/download   (open it once so it runs)
2. ollama pull qwen3:8b      about 5 GB, once
3. dexterm ai engine ollama  run dexterm's AI on the local engine
4. dexterm ai model qwen3:8b
5. dexterm doctor            the "Ollama (local AI)" line should be a ✓

Then press a on a coin, or type a question, as usual. The panel title says ANALYST · ollama and the caption under an answer shows local $0. In the chat box, /engine ollama switches new conversations to the local model and /engine claude switches back.

dexterm never downloads or ships a model: you pull the one you want with Ollama.

Which model#

These are tool-capable models from Ollama's library, a good place to start. They are suggestions, not a dexterm benchmark: dexterm ai probe checks the copy you pulled.

Smaller models answer faster and make more mistakes. A model with no tool calling still works for questions (see models without tool calling).

dexterm asks Ollama for a 32,768-token context window, or the model's own maximum when that is smaller. On a small machine lower it with dexterm ai ctx 16384.

Pick the engine, globally or per surface#

dexterm ai engine <auto|claude|codex|ollama> sets the engine for everything; add --surface analyst|autotrade|agent to set one surface only (for example the analyst on Claude and paper autotrade on the local model). dexterm ai status shows the engine for each surface, the local model, the profile and a quick probe; dexterm ai status --parity adds the full list of what runs where.

For the analyst the order is: --analyst-engine, then DEXTERM_ANALYST_ENGINE, then analyst.engine in config.json, then ai.json, then auto. **auto is unchanged**: Claude Code when it is installed, else Codex, else the local model once you set one up (or Ollama is installed). With none of them, the analyst says how to set up an AI backend, and dexterm doctor lists all three ways.

The settings live in ~/.dexterm/ai.json (mode 0600). Only you write it, with dexterm ai … or by hand. No MCP tool, chat message, Telegram command or model output can change it.

Restriction profiles#

**A new local setup starts at propose.** paper is one command: dexterm ai restrictions paper. **full needs a typed confirmation** on a real terminal: dexterm ai engine ollama --full explains the small-model risk and asks you to type ENABLE FULL. It is recorded for that one model: change the model and the engine runs at paper until you confirm again. Going back to a lower profile forgets the confirmation. It needs you at a real terminal: a pipe cannot confirm it.

What stays outside the model#

Whatever profile you pick, and whichever engine runs:

• your strategy and runner caps, and the kill switch (command, hotkey, the panic file);
• mandate tiers: arming a mandate is a physical keypress, and no model or agent can arm one;
• the strategy clamp: every size a model asks for is cut to your strategy and your runner caps, exactly as for Claude;
• Telegram approvals, when you use them: a one-time button, bound to a nonce, a hash and an expiry and to your account, tapped by you;
• the prompt firewall: token names, socials and page text reach a local model wrapped as <untrusted> data, byte for byte as they reach Claude.

A model can only ask. It cannot raise a cap, arm a mandate or change its own profile. There is no live mode for it to turn on: dexterm trades on paper only.

What runs on a local model#

The Claude usage guard does not apply to a local model (no plan limit, $0); the runner's day caps on sessions and turns still do.

Models without tool calling#

If the model cannot call tools, dexterm fetches the selected coin's dossier itself and the model answers from it, and the answer starts with (… has no tool calling: answering from the dossier without tools). Structured verdicts carry a no_tools_mode flag. For tool use pull a tool-capable model (the table above).

A local model that keeps asking for a tool it does not have is refused each time (the call never runs); after three refusals the turn stops and says so.

Check your model: dexterm ai probe#

dexterm ai probe checks that Ollama answers, the model is pulled, it can call tools, and how much context it has. dexterm ai probe --json also asks it three short trading questions and checks it answers in the decision format the AUTOTRADE runner needs. It warns when the model is below the bar for your profile:

A decision a model cannot format is refused by the engine, which means fewer trades, never bigger ones.

Autotrade on a local model#

dexterm autotrade run <strategy> --paper --engine ollama (or dexterm ai engine ollama --surface autotrade) runs each candidate's session on your local model. The session has no tools: the request to Ollama never carries any, so the model can only answer. Its reply is constrained to {comment, decision} and turned into the same DECISION {…} line a Claude session writes, so the same closed schema, clamp, caps and run file apply. A reply later than the strategy's decision window is no answer. --model <name> picks another local model for the run. The run file records agent: ollama, the model and $0.

The runner needs the paper profile and refuses to start below it, with the command that raises it.

Your own agent, on the local model#

dexterm ai agent "<goal>" runs the local model as an agent on the dexterm MCP server, the way claude -p connected to dexterm mcp would: the read tools at every profile, proposals at propose, and the paper tools at paper (the server still refuses them unless you armed a mandate and turned on agent paper trading in the app). --thoughts FILE writes its words for the spectator's thought ribbon (--spectate-thoughts FILE).

Another machine#

dexterm ai host http://<machine>:11434 points dexterm at an Ollama on another computer you control. Prompts, screen context and tool results then travel over your network, and dexterm ai status, dexterm doctor and each chat answer say so. dexterm contacts no other host for the local engine. It never follows a redirect: if the host answers with one, dexterm sends nothing on, and dexterm doctor and the chat answer say the host redirected.

How we checked#

Offline tests drive a fake Ollama server through the real app paths and the real dexterm MCP server: tool round trips, the tool list each profile offers, refused calls that never run, the no-tools mode, structured verdicts, the typed full confirmation, and the doctor lines. The firewall test checks the local model receives exactly the text the Claude CLI receives. The caps test runs the same decisions through the Claude path's session interface and a local session over a recorded tape and gets identical clamps, refusals and fills. Answer quality and speed of local models against Claude have not been benchmarked.

Troubleshooting#