How-To · 20 min

Add models — every type

Kaptain runs four kinds of model side by side and lets you mix them freely. The + Add a model button behind the chat model picker has three tabs — Cloud API, Ollama, Local GGUF — and CLI harnesses are enabled in setup or Settings. This page covers all four, then the per-model knobs.

Which route, when

You wantRoute
Zero setup, you already use Claude/Codex in a terminalCLI harness — their sign-in, no downloads, no GPU
Everything local, easy managementOllama
Everything local, a specific GGUF buildBuilt-in llama.cpp runtime
Low-powered machineCloud API key — nothing heavy runs locally

RAM rule of thumb for local models: 4B ≈ 8 GB, 12B ≈ 16 GB.

Route 1 · Ollama

  1. Install Ollama once (Kaptain shows the one-line per-OS command in setup; it deliberately won't install it for you). From then on Kaptain auto-starts an installed Ollama when it serves.
  2. Chat model picker ▸ + Add a model ▸ Ollama tab.
  3. Type the model name — anything from ollama.com/library (e.g. qwen3:8b) — and pull. Progress streams live; long pulls keep running if you navigate away.

The setup wizard also offers a small curated starter set — qwen3:4b (2.6 GB), qwen3:8b (5.2 GB), gemma3:12b (8.1 GB), and nomic-embed-text (0.3 GB, embeddings for KodeGraph search).

Route 2 · GGUF / built-in llama.cpp

  1. + Add a model ▸ Local GGUF tab.
  2. Paste a direct .gguf download link (on Hugging Face that's the …/resolve/main/model.gguf form — a page URL is rejected with the reason). Kaptain downloads to a .part file and verifies the file really is GGUF before accepting it, so a broken link can never leave a corrupt model behind.
  3. Files land in the models folder inside Kaptain's data folder — ~/.local/share/kaptain/models on Linux, %LOCALAPPDATA%\Kaptain\models on Windows, ~/Library/Application Support/Kaptain/models on macOS (override with KAPTAIN_MODELS_DIR) — and appear in the picker automatically. Already have GGUF files elsewhere? Scan system for GGUF files finds them.

Vision GGUFs: a vision model needs its projector file (mmproj-*.gguf) beside it. From Hugging Face that is one download — Kaptain reads the repo and fetches the matching projector into the same folder. A GGUF without its projector is not offered as a vision model, and the tool names the missing file.

Kaptain runs GGUF models with its own managed llama-server. Setup can build one for your GPU (Metal, CUDA, or Vulkan — needs git + cmake); if you keep your own binary, point Kaptain at it in Settings and clear the field to return to auto-discovery.

Route 3 · Claude & Codex CLIs

If the claude or codex CLI is installed and signed in, Kaptain can drive it as a model — their subscription, Kaptain's tools and scheduling.

  1. Enable in setup (it detects install + sign-in state per CLI) — or later in Settings.
  2. The model appears as claude-cli / codex-cli in the picker.
  3. Pick the underlying model (e.g. which Claude) in the ⚙ popover next to the composer — options are discovered from your installed binary, defaulting to "CLI default".

Kaptain's own toolbelt reaches these CLIs over MCP automatically inside Kaptain — nothing to install. (To use Kaptain's tools from a standalone terminal session of those CLIs, see MCP servers.)

Not offered: Gemini CLI as a harness model (deliberately, for now). And Claude is not an API-key provider in Kaptain — it's reached via its CLI.

Route 4 · Cloud API keys

  1. + Add a model ▸ Cloud API tab.
  2. Pick a provider preset — OpenAI, Google Gemini, DeepSeek, Groq, Mistral, Together AI, OpenRouter, or Custom (any OpenAI-compatible base URL).
  3. Type the model id your account actually has (Kaptain deliberately doesn't guess provider catalogues for you) and paste the API key.

Keys are stored on the machine and never echoed back to the browser. Rotate them any time in Settings ▸ Providers & keys ▸ Update keys — key-only, atomic, can't clobber the rest of the model's config.

Per-model settings (⚙)

Every model has a ⚙ Model settings popover next to the composer. What you can set per model:

SettingMeaning
Thinkingshow the model's live reasoning stream
Stream tokens livetoken-by-token output
Context window (num_ctx)with the runtime's real default and maximum shown
Max output (tokens)response cap
Tool approvalAsk / Ask before risky / Read-only / Auto-approve in workspace / Full access
Tool callsAuto / Native / Text protocol
Reasoning effortminimal / low / medium / high — shown only for models that support it; discovered from your installed CLI where applicable

Settings are per model, saved field-by-field, and Revert to default really reverts.

One setting is not per model: Settings ▸ Model Handling ▸ Vision tool picks which model processes images when a turn needs to look at one — a local model that declares vision, a GGUF with its projector, a cloud model, a Claude or Codex CLI (which then looks with its own tools), or a paired machine's model — plus the thinking policy (auto / off / on) and two answer budgets.

Agent-readable version: index.md · Every claim on this page was exercised on a real install before being written. Something missing that cost you time? That is a documentation bug — tell us.