Kaptain Docs · Version 0.0.9 · Updated 4 November 2026

Kaptain Docs

Everything about installing, setting up and running Kaptain on one page. Commands come with their real output, and every setting, tool and error is explained.

index.md /llms.txt Release notes
Start

Overview#

Kaptain is one program that runs on your own computer and gives your AI work a single home. Every model you use sits in one picker: local models through Ollama or llama.cpp, cloud models with your own API keys, and the Claude Code and Codex command-line assistants you already sign in to. They share one set of tools, one approval gate, one record of what ran, and one project folder that you choose.

Most AI desks are several tools taped together: a chat subscription, a terminal assistant, a local model runner and a scheduler. None of them share context, tools, permissions or an audit trail, so nothing composes. Kaptain puts all of that in one local runtime. A scheduled agent can hand mechanical work to a local model, using the same tools and leaving the same trace as a live chat.

What Kaptain is made of#

Part What it gives you
The binary One file per platform. It serves the web interface, runs the tools and talks to your models. There is no installer service and nothing else to install for Kaptain itself.
The workbench The browser interface, at http://127.0.0.1:8810 by default: chat, files, tools, agents, traces and settings.
Model routes Ollama, GGUF files through llama.cpp, cloud APIs with your keys, and the Claude Code and Codex CLIs. Mixed freely, changeable per chat and per agent.
Krew The toolbelt models use: files, shell, tests, git, web, code search, delegation, memory and agents. Every risky call passes one approval gate.
Kapsules Agents defined as a folder: a model wrapped with a persona, tools, permissions, memory and an optional schedule.
KodeGraph A graph of your project's code, so models are handed the relevant code instead of reading everything.
BlackBox A record of every turn: the context that was sent, each tool call and its result, the reply and the tokens.
Network Access This machine only, or your own Tailscale network. Kaptain has no internet-facing mode.

Where things run#

Kaptain, your conversations, your settings, your API keys and your project files stay on your machine. CHYNJ's servers hold your account, your licence and your list of devices; a device is identified to them by a hash of its fingerprint. A cloud model you add receives what you send it, under your own key. Downloads Kaptain makes on its own are named where they happen in these docs.

Quick start#

On Linux or macOS:

Terminal
$ curl -sL https://chynj.ca/install.sh | sh
$ kaptain start

If the installer asks you to add Kaptain to your PATH, do that first (PATH step). kaptain start then opens the setup wizard in your browser. On Windows, download kaptain-windows-x64.exe and double-click it. The install and first run chapters walk through every step, and Your first 10 minutes takes it from there.

How to read these docs#

Install#

Kaptain is one binary. Installing it never needs administrator rights, never adds a system service and never starts anything on its own.

Requirements#

You run Build Download
Linux on Intel or AMD, 64-bit linux-x64 /download/kaptain/linux-x64
Linux on 64-bit ARM (Raspberry Pi 4 and 5 with a 64-bit OS, Jetson) linux-arm64 /download/kaptain/linux-arm64
macOS 12 or later, Apple silicon macos-arm64 /download/kaptain/macos-arm64
macOS 12 or later, Intel macos-x64 /download/kaptain/macos-x64
Windows 10 or 11, 64-bit windows-x64.exe /download/kaptain/win

There are no builds for Windows on ARM, 32-bit ARM (such as 32-bit Raspberry Pi OS), 32-bit x86 or RISC-V. The Linux builds are statically linked, so any distribution works. To check which build a Linux or macOS machine needs:

Terminal
$ uname -sm
Linux x86_64

x86_64 means linux-x64 (or macos-x64 on a Mac), and aarch64 or arm64 means the ARM build.

What else the machine needs depends on the models you choose.

Install on Linux#

The installer checks CHYNJ's signature on the release, downloads the right build, checks its SHA-256, and puts it in ~/.local/bin:

Terminal
$ curl -sL https://chynj.ca/install.sh | sh
Output
  Kaptain for CHYNJ
  ──────────────────
  Platform : Linux / x86_64
  Dest     : /home/you/.local/bin/kaptain

  Checking the release signature...
  Release  : <version> — signature verified (openssl)

######################################################################## 100.0%

  Checking the download...
  Checked  : size and SHA-256 match the signed release

  Add Kaptain to your PATH — paste this into your shell profile:
    export PATH="$HOME/.local/bin:$PATH"

  Installed <version> (release signature, size and SHA-256 checked before it ran).

  Next: `kaptain start` — your browser opens setup.

  It opens at http://127.0.0.1:8810.
  Your 3-day trial starts when you create your CHYNJ account in setup. No card needed.

<version> is the release's version name. What the installer does, in order:

  1. Detects your platform with uname, and stops with a clear message on one that has no build.
  2. Downloads the release manifest (releases.chynj.ca/version.json, the same file kaptain update reads) and checks its signature against CHYNJ's release key, which is written into the installer.
  3. Downloads the build to a temporary file next to the destination, and checks its size and SHA-256 against the signed manifest.
  4. Runs the checked binary once. If any check fails, the download is deleted, any existing Kaptain is left untouched, and the installer says why.
  5. Moves it into place as ~/.local/bin/kaptain. An existing Kaptain is updated in place: the same data folder, access code, device and licence, with the old binary kept as kaptain.bak. A running Kaptain is restarted onto the new binary only when no turn is running.
  6. Prints the export PATH line if ~/.local/bin is not on your PATH. It never edits your shell profile.

Note

The signature check needs openssl 1.1.1 or newer, or ssh-keygen from OpenSSH 8.1 or newer; macOS uses the second. The trial does not start at install. It runs for 3 days from when you create your CHYNJ account, normally in the setup wizard, or from this machine's first trial if that was earlier.

Without the installer: download the build from the table above, then:

Terminal
$ chmod +x ~/Downloads/kaptain-linux-x64
$ mkdir -p ~/.local/bin
$ mv ~/Downloads/kaptain-linux-x64 ~/.local/bin/kaptain

Install on macOS#

The same installer works on macOS 12 or later.

Terminal
$ curl -sL https://chynj.ca/install.sh | sh

Without the installer: download kaptain-macos-arm64 (Apple silicon) or kaptain-macos-x64 (Intel). The macOS builds are not yet notarized by Apple, so a file downloaded in a browser is blocked the first time it runs. Clear the block, make the file executable and move it into place:

Terminal
$ chmod +x ~/Downloads/kaptain-macos-arm64
$ xattr -d com.apple.quarantine ~/Downloads/kaptain-macos-arm64
$ mkdir -p ~/.local/bin
$ mv ~/Downloads/kaptain-macos-arm64 ~/.local/bin/kaptain

Install on Windows#

Download kaptain-windows-x64.exe and run it. The commands on this page for Windows are PowerShell commands: open PowerShell from the Start menu, not the old Command Prompt, where $env:LOCALAPPDATA means nothing (Command Prompt writes the same folder as %LOCALAPPDATA%).

Before you run a file you downloaded in a browser, you can check it against the SHA-256 CHYNJ published. In PowerShell, go to your Downloads folder first:

PowerShell
PS> cd $HOME\Downloads
PS> $m = Invoke-RestMethod https://releases.chynj.ca/version.json
PS> (Get-FileHash .\kaptain-windows-x64.exe -Algorithm SHA256).Hash -eq $m.assets.'kaptain-windows-x64.exe'.sha256
True

True means it matches. False means delete it and download it again. In Git Bash, the installer script works too: it downloads the .exe into the current folder and checks it the same way, but never runs it.

  1. Windows SmartScreen may say "Windows protected your PC", because the build is not yet signed. Choose More info, then Run anyway. This happens once.
  2. Double-clicking the file starts Kaptain in the background and opens your browser on the setup wizard. The console window closes by itself; Kaptain keeps running.
  3. To use it from a terminal, do the PATH step for Windows. Then kaptain start, kaptain status and kaptain stop work from PowerShell.

From PowerShell in the download folder, without renaming:

PowerShell
PS> .\kaptain-windows-x64.exe start

Run with no command from a terminal, the binary prints its command list and exits. Models' shell commands on Windows run through Git Bash; see Agent Shell (Windows) in the Settings reference.

Add Kaptain to your PATH#

The installer puts Kaptain in ~/.local/bin. Your shell finds kaptain only if that folder is on your PATH, and the installer never edits your shell settings for you. Skip this step if kaptain version already works in a new terminal.

bash (most Linux)

Terminal
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

zsh (macOS)

Terminal
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

fish

Terminal
$ fish_add_path ~/.local/bin

Windows (PowerShell)

These are PowerShell lines; open PowerShell from the Start menu, not Command Prompt. The first line goes to the folder the browser downloaded to:

PowerShell
PS> cd $HOME\Downloads
PS> New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\Programs\Kaptain"
PS> Move-Item .\kaptain-windows-x64.exe "$env:LOCALAPPDATA\Programs\Kaptain\kaptain.exe"
PS> [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Programs\Kaptain", "User")

Then close PowerShell and open a new window, so it reads the new PATH. What the lines do, and where things are:

  • $env:LOCALAPPDATA is your own C:\Users\<your name>\AppData\Local. Every Windows account has its own, under its own user folder, so each person who uses the computer has their own folder and their own Kaptain.
  • The New-Item line creates the folder Programs\Kaptain inside it. cd "$env:LOCALAPPDATA\Programs\Kaptain" works only after that line has run.
  • AppData is a hidden folder, so Explorer does not show it while you click through your user folder. To open it, run explorer $env:LOCALAPPDATA in PowerShell, or paste %LOCALAPPDATA% into Explorer's address bar and press Enter.
  • In Command Prompt the same folder is %LOCALAPPDATA%: cd %LOCALAPPDATA%\Programs\Kaptain.

Two folders, kept apart. The program is %LOCALAPPDATA%\Programs\Kaptain\kaptain.exe. Kaptain's data, kaptain.json with your access code, your chats (sessions.db) and your models list and keys (models.db), is in %LOCALAPPDATA%\Kaptain\, which Kaptain creates on its first start (The data folder). Deleting the program leaves the data; kaptain uninstall removes both.

Then open a new terminal and check the install. Not sure which shell you use? echo $SHELL prints it. To start Kaptain without changing your PATH, use the full path instead: ~/.local/bin/kaptain start.

Check the install#

Terminal
$ kaptain version
kaptain <version>
claude sidecar: embedded (linux-amd64, <size> MB)

First run#

The first run is three things in order: start Kaptain, answer the setup wizard (in your browser, or in the terminal on a machine without one), and keep the access code it shows you. You agree to CHYNJ's Terms of Service before you download Kaptain from chynj.ca, where the install dialog asks first, and before your CHYNJ account is created, in setup or at chynj.ca/account. Signing in uses that account; it does not ask again.

Start Kaptain#

Terminal
$ kaptain start
kaptain started (pid 3150395)
  UI:    http://127.0.0.1:8810
  bind:  127.0.0.1:8810
  logs:  /home/you/.local/share/kaptain/kaptain.log
  stop:  kaptain stop

What Kaptain does on its own around the first start:

Note

Kaptain works inside one project folder. Until the wizard sets one, it is the folder you ran kaptain start from, so run the first start from your home folder or the project you want to work in.

The setup wizard#

The wizard runs once in your browser, and everything it sets can be changed later in Settings.

  1. Account
    • Do. Press Sign in and sign in to your CHYNJ account, or press Create account and tick I agree to the Terms of Service and Privacy Policy. Passwords are at least 12 characters. If your account uses two-factor sign-in, the wizard asks for the 6-digit code.
    • You should see. The Plan step. Signing in to an account you already have does not ask again. A new account works at once; its free trial waits until you verify your email.
    • If nothing happens. The box and Create account stay off until the wizard has read the current Terms from CHYNJ; if it cannot, it says "Can't confirm the current Terms right now; try again shortly." with Try again. If the Terms change while the form is open, the wizard shows the new ones, unticks the box and asks again. From a place CHYNJ cannot serve, no account is made and the wizard says why.
    • Why. The account holds your licence and trial, and CHYNJ records which versions of the Terms you agreed to, and when. An account is required. Kaptain itself has no sign-in, and the account is not how a browser reaches it (that is the access code).
  2. Plan
    • Do. Press Start Free Trial. With a paid plan, open Have a license key? and save your key (KAPTAIN-XXXXXXXX-XXXX-XXXX) on this machine instead.
    • You should see. Your plan's state. The trial is 3 days on this machine, with no card; the 3 days count from when your CHYNJ account was created, or from the first trial on this machine if that was earlier. With a paid plan, this step may still offer the trial on a new machine.
    • If nothing happens.
      • Connect to verify your plan with Retry: the wizard cannot reach CHYNJ. It needs an internet connection.
      • A key typed with no account signed in is refused with "A licence key alone never registers this computer — sign in to your CHYNJ account" and the button Sign in to your CHYNJ account, which goes back to the account step and keeps the key for you.
      • If CHYNJ refused this machine, for example because its trial was already used, the step's title is CHYNJ's reason, with a box for a licence key and Save key & Continue.
    • Why. The wizard says it plainly: "A licence key alone never registers a computer. Signing in is always required." Finish setup registers the machine on your paid licence because you are signed in (How a computer gets registered). The trial belongs to this machine; reinstalling does not restart it.
  3. Models
    • Do. Under Choose your models, tick what you want to use: one box each for the Claude CLI, the Codex CLI, Ollama and llama.cpp. Choosing nothing is fine, and you can tick both CLIs.
    • You should see. For each one, whether it is here and where it was found, starter models sized to this machine's memory, and how to install what is missing. The first box you tick (Claude, Codex or an Ollama model) becomes the default.
    • If something is missing. A missing CLI shows its own one-line installer to copy. Install llama.cpp for me downloads the official llama.cpp build (GGUF); on Linux, Install Ollama for me asks for your computer password once and runs Ollama's installer. The page re-checks every few seconds.
    • Why. This chooses your default model. You can switch per chat later.
  4. Installing
    • You should see. One row per download, with its progress until it reports Installed. This step appears only when something is downloading.
    • If it fails. The row shows the reason, with Retry.
  5. Project
    • Do. Under 1 · Project folder, pick a folder with the folder picker, which suggests a new folder and creates it, or type the full path of an existing folder. Under 2 · Semantic code search, choose Use Ollama, Use Kaptain's built-in runtime (llama.cpp) or None — keyword-only search.
    • You should see. The folder accepted. Kaptain adds a .kodegraph/ index there.
    • If nothing downloads. That is expected with Ollama or None: only the built-in runtime downloads anything (Start Kaptain).
    • Why. Kaptain works inside one project folder, and code search is how it finds code by meaning.
  6. Network
    • Do. Under Who can reach Kaptain?, keep Local only (recommended, preselected) or choose Remote + local — Tailscale, then press Finish setup.
    • You should see. Tailscale offered only when it is installed and connected (Network and remote access).
    • If registration fails. The wizard says why and setup stays open. The usual causes are an unverified email on a trial account, a trial already used on this machine, or a licence that already has its maximum number of devices. CHYNJ also refuses accounts, trials and licence renewals from places Canadian sanctions law does not let it serve (Licence and devices).
    • Why. Local only means nothing off this machine can connect. Finish setup is the moment this machine is registered with your account.
  7. Done
    • You should see. You're all set, with Your access code — save it now and Copy code. The code is shown once.
    • Do. Copy the code somewhere safe (Your access code). If you chose Tailscale, press Restart Kaptain now: it restarts Kaptain on the tailnet address and reopens the page there. Not now — open Kaptain here waits for your next restart.
    • Why. Any other browser or device asks for this code before it can use this Kaptain.

Your access code#

Warning

Nothing in Kaptain shows the access code again. kaptain status prints where it is: access-code.txt while that file exists, otherwise api_token in kaptain.json. Delete access-code.txt once your devices are paired. To replace the code, see Get a new access code.

Get a new access code#

In Settings

In a terminal

Output
Kaptain made a new access code for this computer.
  Access code (shown once — save it): chynj_…
  Saved to /home/you/.local/share/kaptain/access-code.txt (only you can read it).
  The old code has stopped working: every browser and device must pair again with the new one.
  Cluster tokens you issued to other Kaptains keep working; cancel any of them in Settings › Network Access.
  The running Kaptain (pid 4121449) uses the new code now.

Either way

Kaptain serves only with a code it made

Output
kaptain: the access code (api_token) in /home/you/.local/share/kaptain/kaptain.json is too short (4 characters; Kaptain makes codes of 32 or more) — Kaptain will not serve with it; run "kaptain access-code rotate" to get a generated one

By hand, as a fallback. If you cannot run kaptain on that computer, put a generated code in place yourself:

  1. Stop Kaptain: kaptain stop.
  2. Make a code of the shape Kaptain makes. On Linux or macOS, this prints one; copy it:
    Terminal
    $ echo "chynj_$(openssl rand -hex 24)"
  3. Open kaptain.json in the data folder in a text editor (~/.local/share/kaptain/kaptain.json on Linux). Replace the value of "api_token" with the new code, keep the quotes, change nothing else, and save. Delete access-code.txt in the same folder if it is there: it holds the old code.
  4. Start Kaptain: kaptain start.
  5. Pair every browser and the app again. Each one shows Pair this browser with Kaptain; enter the new code.

Set up from the terminal#

On a machine without a browser, such as a server or a Raspberry Pi, the same setup runs in the terminal, against the same steps as the browser wizard. Stop Kaptain first, because the terminal wizard serves on the same port while it runs:

Terminal
$ kaptain setup

It asks one question at a time. Pressing Enter takes the answer shown in brackets [ ] when there is one, else the one in parentheses ( ). The password and licence key prompts do not show what you type. Step by step:

  1. Account. Sign in, create an account, or skip for now? [signin/signup/skip]:
    • signin asks Email: and Password:, and Enter your 6-digit authenticator code: if your account uses two-factor sign-in.
    • signup prints the links to the Terms of Service and the Privacy Policy and asks Do you agree to the Terms of Service and Privacy Policy? [y/N]:. Only y (or yes) goes on, to Name:, Email: and Password (12+ chars):. Any other answer stops setup, and no account is made. Setup also stops, with the reason and no account, when Kaptain cannot read the current Terms from CHYNJ, or when CHYNJ refuses the account, for example because you are connecting from a place it cannot serve. Once the account is made it says "Account created. Its free 3-day trial started now (or with this computer's first trial, if that was earlier) — no card needed."
    • skip prints "Skipped — continuing without an account: this computer is not registered and no trial starts. Kaptain cannot be used until it is registered — run kaptain device register after setup." Setup still finishes; register the machine afterwards to use it. A failed sign-in prints its reason, then the same words.
  2. Plan. It shows your plan's state, then License key (Enter to skip):. Press Enter unless you have a key. A licence key alone never registers this computer — sign in. Typed with no account signed in, a key is answered with that sentence and Sign in now and keep this key? [Y/n]:; Enter signs you in and keeps the key, so you never type it twice.
  3. Models. Under What this machine has: it lists the Claude CLI, the Codex CLI, Ollama and llama.cpp, each Ready, Found or Not found, with where it was found. Then it asks only what applies here:
    • Download llama.cpp b10106 for you now (into Kaptain's own folder, no administrator rights)? [y/N]: when llama.cpp is missing.
    • Install Ollama for you now? It installs a system service, so you will type this computer's password. [y/N]: on Linux when Ollama is missing; y asks This computer's password (for sudo): once.
    • Press Enter to go on — or type check to look again after installing or signing in when something is missing that you install yourself, such as a CLI. Type the full path of a command Kaptain did not find to point it there.
    • Use the Claude CLI? [y/N]: and Use the Codex CLI? [y/N]: for each CLI that is installed. You can say yes to both.
    • Ollama models Kaptain can download for you: and GGUF models Kaptain can download for llama.cpp: list the starter models, each marked for this machine's memory, then ask Download which? Numbers separated by commas, Enter for none:.
    • Which should Kaptain use by default? [claude/codex/ollama] (claude): when you chose more than one. You can switch per chat later.
  4. Project directory. It offers 1) /home/you/Kaptain (a new folder, created now) and, when you ran it from another folder, 2) this folder: …, then asks Choose 1 or 2, or type the full path of a folder [1]:. A folder it cannot use is refused with the reason, and it asks again.
  5. Code search. Right after the folder: Which? [ollama/managed/none] (ollama):. ollama uses Ollama. managed is Kaptain's built-in runtime, which downloads nomic-embed-text v1.5 (about 146 MB) when you answer. none is keyword-only search and downloads nothing. The default in parentheses is Ollama when it is running here, otherwise managed.
  6. Network. Who can reach Kaptain? [localhost/tailscale] (localhost):. Enter keeps Kaptain on this machine only. tailscale is offered only when Tailscale is installed and connected, and is never preselected (Network and remote access).
  7. Done. It prints Kaptain is set up. and Access code (shown once — save it): chynj_…, saves the code to access-code.txt in the data folder, and ends by telling you to run kaptain serve or kaptain start. If nothing can run a model yet, the first line says so and names what to add.

The models step onward, from a run on a machine that already had both CLIs, Ollama and llama.cpp, started from the home folder, with every download declined (trimmed, and this machine's paths shortened):

Output
3. Models

  What this machine has:
  Claude CLI  Ready — signed in · /home/you/.local/bin/claude
  Codex CLI   Ready — signed in · /home/you/.npm-global/bin/codex
  Ollama      Running · /usr/local/bin/ollama · 9 model(s) downloaded
  llama.cpp   Ready · /home/you/llama/llama.cpp/build/bin/llama-server
              Uses Vulkan0: AMD Unknown (RADV RENOIR) (34192 MiB, 33720 MiB free)
              4 chat GGUF model(s) found — ready to use.
  Use the Claude CLI? [y/N]: n
  Use the Codex CLI? [y/N]: n
  Ollama models Kaptain can download for you:
    1) Qwen3.5 0.8B — 1.3 GB · Fits this machine
    2) Qwen3.5 2B — 2.7 GB · Fits this machine
    3) Qwen3.5 27B — 17.5 GB · Fits this machine
    4) Qwen3.5 35B-A3B — 22.1 GB · Fits this machine (recommended)
    5) Qwen3.5 122B-A10B — 81.4 GB · Needs more memory — about 81.6 GB at an 8K context; this machine has 63.1 GB (61.5 GB after what the system needs)
  Download which? Numbers separated by commas, Enter for none: none
  ...

4. Project directory
  1) /home/you/Kaptain (a new folder, created now)
  Press Enter for 1, or type the full path of a folder [1]:

  Code search (KodeGraph)
  With Kaptain's built-in runtime, its embedding model (nomic-embed-text v1.5 (~146 MB)) downloads when you answer, so it finds code by meaning, not just keywords.
  Nothing downloads before that, and nothing ever with none.
    ollama   — use Ollama, detected at http://127.0.0.1:11434
    managed  — Kaptain's built-in runtime (llama.cpp), already present
    none     — keyword-only search: nothing is downloaded, noticeably weaker. You can turn it on later in Settings.
  Which? [ollama/managed/none] (ollama): none
  Kaptain will work in /home/you/Kaptain.

5. Network
  Tailscale detected at 100.x.y.z — choose tailscale to reach Kaptain from your other devices.
  Who can reach Kaptain? [localhost/tailscale] (localhost):

Kaptain is set up.
  Access code (shown once — save it): chynj_…
  Saved to /home/you/.local/share/kaptain/access-code.txt (only you can read it).
  This Kaptain is local-only: open http://127.0.0.1:8810 in a browser on this machine.
  To use it from your phone or another computer, turn on Tailscale in Settings ▸ Network Access.

Run `kaptain serve` (or `kaptain start`) to use Kaptain now.

Delete access-code.txt once your other devices are paired. A wizard stopped part-way goes on where it stopped the next time you run kaptain setup; the steps already done print one line each. On a machine that is already set up, kaptain setup changes nothing and says so: "Kaptain is already set up here — … Nothing to do. Change choices in Settings, or run kaptain setup --force to go through the wizard again (your access code, device and licence stay)."

Run setup again#

Customise before your first run#

Kaptain ships with defaults that work, but they are not tuned to your machine or your work. These are the settings worth choosing on purpose before you rely on Kaptain. Each one is a trade-off, and each can be changed later without losing anything. The examples come from one owner's setup and show the kind of choice you might make, not a recommendation for yours.

# Setting Where Default
1 Project folder Settings › General › Project Directory the folder Kaptain was started from
2 Your chat model the model picker in Chat the wizard's pick, remembered per browser
3 Tools and Delegate the two switches next to the picker off
4 Tool approval the ⚙ next to the picker Ask
5 Delegation worker and Summarizer Settings › Model Handling worker: none (Choose a model); summarizer: the worker, else a model on this machine
6 Context window for local models the ⚙ next to the picker at most 8192 on Ollama
7 Compaction Settings › Model Handling › Context & Compaction every 20 messages
8 Network mode Settings › Network Access Localhost only
9 Vision tool Settings › Model Handling › Vision tool Automatic
10 Run memory for scheduled agents each kapsule's settings off

1. Project folder. Every tool a model uses (files, shell, skills, delegation) and the KodeGraph index are rooted here. A broad folder gives models more reach and makes indexing slower; a narrow one is faster and safer. A home folder is never re-indexed automatically. Set it under Settings › General › Project Directory with Set & Index; it applies immediately.

2. Your chat model. The wizard saves your first choice as the default. The model you pick in Chat is remembered by that browser, so a phone and a laptop can use different models. Agents without their own model use the default chosen at startup, so give each kapsule an explicit model if it should not follow yours.

3. Tools and Delegate. Both switches in the Chat header start off, and this browser remembers how you leave them. With both off, a chat is plain conversation with no tool loop. Turn on Tools when you want the model to read files, run commands or search. Delegate hands mechanical work to the worker model and needs Tools on. The tool loop adds latency on a slow GPU, so leave it off for quick questions.

4. Tool approval. Each model has an approval mode: Ask (default), Ask before risky actions (the two Ask choices behave the same), Read-only, Auto-approve in workspace or Full access (unrestricted). Ask pauses for you before anything risky. Auto-approve and Full access run without prompts. For agents that run on a schedule, set the kapsule's own Permissions on purpose: on Ask, an unattended run stops at its first risky step. See Tools and approvals.

5. Delegation worker and Summarizer. The worker runs delegated briefs, and the summarizer writes the rolling summary that keeps long chats inside the model's window. No worker is chosen for you: Settings › Model Handling › Delegation shows Choose a model, and delegation stays off until you pick one and press Save. With no summarizer chosen, Kaptain uses the worker, then a GGUF or Ollama model on this computer, then a model on a paired machine, then a cloud model; it never uses Claude or Codex for summaries unless you choose one. If no model can write the summary, Kaptain folds the older messages into a text-only summary without a model, and the chat's context card says so: "summarised without a model (none can chat) — pick a summary model in Settings".

One owner's setup

The summarizer is a small model on another of the owner's machines (node:<their other computer>/gemma4:e4b), so summaries cost this machine nothing. Any model in the picker can do this job, including one you lend yourself from another computer (Pairing machines).

6. Context window for small local models. The context window (num_ctx) is everything the model sees at once: instructions, tools, history and room for the reply. Ollama models default to half their advertised window, capped at 8192 tokens, even when the model advertises 128K or more. GGUF models default to half their advertised window, cut to fit your free memory. A bigger window holds more history and tool output but needs more memory: the cache grows with the window, and a 4B model at 131K tokens can need about 19 GB for it. Change it per model with the ⚙ next to the picker; the value is capped at the model's advertised maximum.

One owner's setup

A 1.5B Ollama model advertises 131,072 tokens and runs at 8,192, the default. A 26B model on the owner's other machine runs at 32,000 tokens with 24,000 for output, set on that machine and followed here.

7. Compaction. When a chat on a local or cloud model grows, Kaptain folds older messages into a summary. The defaults: compact after 20 new messages, always keep the 2 most recent verbatim, and write at most 1,200 words. A lower threshold keeps prompts small for small windows but summarizes more often. Compact inside long turns (off by default) lets a long tool-heavy turn summarize its own earlier steps and keep going. Claude and Codex manage their own context, so compaction does not apply to them.

One owner's setup

The owner keeps 20, 2 and 1,200 and turns Compact inside long turns on, so long tool-heavy turns finish instead of stopping at the window.

8. Network mode. Localhost only (the default) means nothing outside this machine can connect. Tailscale lets your own devices on your tailnet pair with this Kaptain, for example your phone. Changing the mode needs a restart, which the card offers as Restart Kaptain now, and in Tailscale mode even this machine reaches Kaptain at its tailnet address. See Network and remote access.

9. Vision tool. When a model needs to look at an image, Kaptain hands it to the vision model. Automatic uses your chat model if it can see images, otherwise the first Ollama model that can. You can pick a local model, a GGUF with its projector file, a cloud model, a Claude or Codex CLI, or a model on a paired machine, and choose whether it may think first. See Images and vision.

10. Run memory for scheduled agents. Off by default: each scheduled run starts fresh from its task, the way you would brief a person. Turn Remember previous runs on only when a job builds on its own last answer, such as a tracker that must know what it already reported. See Schedules and run memory.

Code search downloads its files only when you choose Kaptain's built-in runtime; Start Kaptain says what they are and how to stop them. Everything else, every setting and what it does, is in the Settings reference.

Use

Your first 10 minutes#

Setup is done and Kaptain is running. This is the path from an empty screen to a model doing work in your project folder.

  1. Open Kaptain. kaptain start opens your browser. Otherwise open http://127.0.0.1:8810 on this machine, or http://100.x.y.z:8810, this machine's tailnet address, in Tailscale mode. A browser that has not paired yet shows Pair this browser with Kaptain: paste the access code (chynj_…) and press Connect. The browser stays paired for 14 days.
  2. Pick a model in the picker at the top of Chat. It says Choose a model until one is chosen; Pick a model below says which kind to pick. Your choice is remembered in this browser.
  3. Ask something. Type a question and press Enter. With Tools off, this is a plain conversation: fast, and nothing on your computer is touched.
  4. Let it work. Turn on Tools next to the picker, then ask for something in your project, for example "List the files in this project and summarize the README." Each tool call the model makes folds under its answer; open one to see the request and the result.
  5. Answer a permission pop-up. In the default Ask mode, anything that could change something stops at Permission required ("Kaptain is paused until you decide."), with Review tool input, Deny and Allow once. Reading inside the project never asks. Tools, approvals and safety explains each mode.
  6. Read the status under the answer. A turn that did not do its whole job says so in a line of its own (Run status).

Pick a model#

You have Pick Thinking and effort
Ollama with a model pulled its name, such as qwen3.5:4b Thinking on or off; Reasoning per step for models that think
A GGUF file and llama.cpp gguf:<file>.gguf the same as Ollama
A cloud API key cloud:<model id>, after + Add a model… › Cloud API Reasoning effort when you ticked reasoning for it
Claude Code or Codex installed and signed in claude-cli or codex-cli Reasoning effort: the levels your installed Claude Code reports (low, medium, high, xhigh and max today); the levels your installed Codex reports for its model

The ⚙ next to the picker holds these per model. Thinking shows the model's reasoning as it writes; off is faster and quieter. Reasoning per step sets how much a local or cloud model may think before each step: Auto — sized from the room left in the window, No limit from Kaptain, or Fixed number of tokens. Reasoning effort starts on Provider default (CLI default for a CLI). A control the model does not support is not shown. The Models and runtimes chapter has every route and setting.

Switching models in the middle of a chat is allowed at any time. The chat shows a divider, model changed: <old> → <new>, and the conversation goes on:

Run status#

Every turn ends with one of five outcomes. The chat shows the word; BlackBox and the kapsule board show it too.

The chat shows Recorded as What it means
nothing; BlackBox shows Done complete The turn finished: no change it made failed, and its review did not flag the final answer.
Incomplete — reason incomplete It finished, but a change failed and is not in place, or the final answer failed its review. The reason names it, such as "1 change failed and is not in place: …".
Not verified — reason unverified It finished, but the review could not judge the answer, for example "the review did not finish in time".
ERROR row with Retry, or Failed — reason failed The model returned an error, gave no answer, or the turn hit a limit. Retry sends the same message to the same model again.
STOPPED row stopped You pressed Stop, Kaptain shut down, or the browser disconnected.

A turn that stops early says why, in words and with the setting behind it: for example stall guard: no model output or tool progress for 12m0s (stall_timeout), or stopped by the user: Stop was pressed. Some limits do not end the turn but make the model answer with what it has, with a note in the chat: tool-round budget reached (50 rounds) (the max_tool_rounds setting) or context window nearly full. The Troubleshooting table lists the reasons and what to change.

When a tool result is too big#

A model's window has room for only so much tool output. One result may use 15% of the window and all of a message's results together 30% (tool_result_window_percent and turn_results_window_percent in kaptain.json). A result larger than its share is never cut and never lost:

  1. Kaptain saves the whole result, in the run's record and as a file in results/<session>/ in the data folder.
  2. The model gets a notice instead of the content: how big the result is, its shape (a sketch of its fields or lines), the result id, and how to read it. It is told to say what part it read before it summarizes the result or claims something is not in it.
  3. The model reads the parts it needs by id with tool_result_recall: one item, a search across all of it, or a page of lines.

The tool card in the chat shows saved as <id> (N items); the model got a notice with how to read it. When a turn's results have used most of their share, a note says so and the next results arrive the same way. tool_result_recall has the parameters.

The workbench#

The workbench is Kaptain's browser interface. An activity bar on the left switches between eight views; the sidebar next to it shows what belongs to the current view.

View What it is for
Chat The main conversation, with the model picker, the Tools and Delegate switches and the ⚙ model settings in its header. The sidebar lists saved chats.
Views Two explorers. Deview opens, edits and previews the files, images and databases in your project, with project-wide search and Markdown rendered as an editor would; right-click a file or folder for Copy path or Copy relative path. God's Eye draws your project as a graph from the KodeGraph index.
Krew The tools. Native Tools lists every built-in tool with its own switch, MCP Servers manages the servers you connect, and Skills holds instruction documents models can load.
Kapsules Your agents. Each has its own chats, settings, schedule and jobs.
Channels Chat surfaces outside Kaptain, each one your own bot run from this machine.
BlackBox What happened: every turn's context, tool calls, reply and tokens, and model usage totals.
Settings General, Model Handling, Runtimes and Network Access. See the Settings reference.
Brain Logs Kaptain's own runtime log events.

Working in a chat#

Each kapsule has its own chats as well, so a question you ask an agent stays with that agent and never lands in your main chat.

Models and runtimes#

Kaptain reaches models four ways and treats them alike: every route works in chat, in kapsules, as the delegation worker and as the summarizer. Mix them freely.

Route Best when What it needs
CLI harness (claude-cli, codex-cli) You already use Claude Code or Codex and want their models with Kaptain's tools and scheduling The CLI installed and signed in. No model download, no GPU.
Ollama You want local models with the least effort Ollama installed; memory for the model
GGUF through llama.cpp You want a specific GGUF file and direct control A llama-server binary; memory for the model
Cloud API A low-powered machine, or a model only a provider hosts An API key and the model id your account has

A fifth source is another of your machines: once two Kaptains are paired, the other machine's models appear in your picker under its name.

Spend strength where it matters. A strong model is worth it for ambiguous reasoning, planning and final judgement; a cheaper or local model is enough for mechanical, reviewable work. Delegation does that split for you.

Ollama#

Kaptain finds Ollama on your PATH and starts it when it is installed but not running. Ollama installs a system service, so Kaptain never installs it on its own. On Linux, Install Ollama for me, in the setup wizard's Ollama box or under Settings › Runtimes › Ollama Runtime, installs it when you ask: Kaptain asks for the password you log in to this computer with, downloads Ollama's official installer, shows the start of its SHA-256 checksum and runs it with administrator rights. The password is used once and never stored. On macOS and Windows, or to do it yourself:

Linux

Terminal
$ curl -fsSL https://ollama.com/install.sh | sh

macOS

Terminal
$ brew install ollama
$ ollama serve

Windows

PowerShell
PS> winget install Ollama.Ollama

Then pull models from Kaptain: open the model picker, choose + Add a model…, go to the Ollama tab, type any name from the Ollama library (for example qwen3.5:4b) and press Pull Model. Progress shows live. The setup wizard offers a starter set when Ollama is running, and the same models as GGUF files for llama.cpp:

Model Ollama download GGUF download
Qwen3.5 0.8B (qwen3.5:0.8b) 1.3 GB 0.7 GB
Qwen3.5 2B (qwen3.5:2b) 2.7 GB 2.0 GB
Qwen3.5 4B (qwen3.5:4b) 3.3 GB 3.4 GB
Qwen3.5 9B (qwen3.5:9b) 6.6 GB 6.6 GB
Qwen3.5 27B (qwen3.5:27b) 17.5 GB 17.7 GB
Qwen3.5 35B-A3B (qwen3.5:35b) 22.1 GB 22.9 GB
Qwen3.5 122B-A10B (qwen3.5:122b) 81.4 GB 77.4 GB

Each one is marked for this machine: Fits this machine, or Needs more memory with the memory it would need at the context window it would run at (8K for Ollama) and what this machine has. The largest one that fits is marked recommended. Models you already have are shown as Installed and cannot be ticked. All of them can use tools, think and see images.

Kaptain talks to Ollama at http://127.0.0.1:11434. To use another address, set ollama_url in kaptain.json or the KAPTAIN_MODEL_URL environment variable. Ollama models default to a context window of at most 8,192 tokens; raise it per model with the ⚙ model settings. Settings › Runtimes › Ollama Runtime shows the installation, version and GPU in use, with start and stop buttons.

GGUF files and llama.cpp#

Kaptain runs a GGUF file with llama-server from llama.cpp, one server per loaded model, on 127.0.0.1 starting at port 8090. The setup wizard's Install llama.cpp for me, or Install llama.cpp now under Settings › Model Handling › KodeGraph Embedder while no llama.cpp is installed, downloads the official llama.cpp release b10106 into the data folder (runtimes/llama.cpp/), checks that llama-server runs, and saves it as the Executable path below. No compiler is needed. It tries the builds your GPU can use first (Vulkan or ROCm on Linux; CUDA, Vulkan or ROCm on Windows; Metal on Apple silicon) and the CPU build last, and keeps the first one that runs. llama.cpp publishes no CUDA build for Linux, so an NVIDIA GPU on Linux gets the Vulkan build; Build llama.cpp for this GPU in Settings › Runtimes › llama.cpp Runtime builds it from source for CUDA. When the machine has a GPU but only the CPU build runs, the install says DEGRADED: this build runs on the CPU only and names the GPU it is not using. If llama-server cannot start because the system lacks a library, such as libgomp1 on a minimal Ubuntu, Kaptain names it, offers Install libgomp1 for me (Linux, with your computer password), and shows the command for your package manager. On a platform without a release build, the wizard builds llama.cpp from source, which needs git, cmake and a C++ compiler. A llama-server you installed any other way works too, if it is on your PATH or its path is set in Settings.

Kaptain looks for llama-server in this order: the KAPTAIN_LLAMA_SERVER_BIN environment variable, the path saved in Settings › Runtimes › llama.cpp Runtime › Executable path, your PATH, ~/llama/llama.cpp/build/bin/llama-server, /usr/local/bin/llama-server, then Kaptain's own install under runtimes/llama.cpp/ in the data folder. Use auto-detect clears a saved path.

Add a GGUF model: open + Add a model…, go to Local GGUF and paste a direct download link. For Hugging Face that is the …/resolve/main/<file>.gguf form, not the model's page. Kaptain downloads to a .part file, checks that the file really is a GGUF, and only then gives it its name, so a broken link never leaves a corrupt model behind. Downloads go to ~/.local/share/kaptain/models on every operating system, even when KAPTAIN_DATA_DIR points elsewhere, or to KAPTAIN_MODELS_DIR if you set it.

GGUF files you already have are found automatically in these folders: KAPTAIN_MODELS_DIR, OLLAMA_MODELS, LLAMA_MODELS_DIR, ~/models, ~/llama, ~/gguf, ~/.local/share/kaptain/models, ~/.cache/huggingface/hub and /opt/models. Scan system for GGUF files in the same dialog re-runs that search.

A GGUF model's context window defaults to half of what the model was trained for, cut to fit your free memory. Saving a new window in the ⚙ restarts that model's llama-server on the next message.

Vision GGUFs need their projector file, the publisher's mmproj-*.gguf, in the same folder as the model. A Hugging Face link for a vision model downloads both in one step. A GGUF without a projector is not offered as a vision model.

Claude Code and Codex#

If the claude or codex command-line assistant is installed, Kaptain lists it in the picker as claude-cli or codex-cli and drives it as a model: your subscription and sign-in, with Kaptain's tools, scheduling, approvals and traces. There is no switch to turn them on; being on your PATH is enough. Install and sign in with the CLI itself. When a CLI is not found, its box in the setup wizard shows these commands for your system, each with a Copy button:

Linux

Terminal
$ curl -fsSL https://claude.ai/install.sh | bash
$ claude
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
$ codex

macOS

Terminal
$ curl -fsSL https://claude.ai/install.sh | bash
$ claude
$ curl -fsSL https://chatgpt.com/codex/install.sh | sh
$ codex

Windows

PowerShell
PS> irm https://claude.ai/install.ps1 | iex
PS> claude
PS> npm install -g @openai/codex
PS> codex

Running claude or codex once signs you in. With Node 18 or newer, npm install -g @anthropic-ai/claude-code and npm install -g @openai/codex work too. A CLI that is installed but not signed in shows Found, not signed in in the setup wizard.

These are each CLI's own installer. On Linux and macOS both put the command in ~/.local/bin.

In the ⚙ model settings for a CLI model:

Kaptain Claude Code Codex
Ask default mode, with Kaptain asking you untrusted approvals, workspace-write sandbox
Auto-approve in workspace accept edits on-request approvals, workspace-write sandbox
Read-only plan mode never ask, read-only sandbox
Full access bypass permissions never ask, full access

Kaptain's tools reach the CLI as an MCP server named kaptain-engine, attached to every turn. Each CLI also keeps the MCP servers you added to it yourself, and Claude keeps your own Claude settings and skills. Kaptain's own older entries there are switched off for the session, so the CLI never sees Kaptain twice. A server you added to one CLI works only in that CLI: connect it to Kaptain instead (MCP) and every model can. A CLI waits up to 900 seconds for a Kaptain tool such as a long delegation or image description; set KAPTAIN_CLI_TOOL_TIMEOUT_S to change that.

The Gemini CLI is not offered as a model, and Anthropic's API is not a cloud provider; Claude is reached through Claude Code.

Cloud models#

Open + Add a model…, go to Cloud API, choose a provider and fill in the fields:

Provider Base URL Kaptain fills in
OpenAI https://api.openai.com
Google Gemini https://generativelanguage.googleapis.com/v1beta/openai
DeepSeek https://api.deepseek.com
Groq https://api.groq.com/openai
Mistral https://api.mistral.ai
Together AI https://api.together.xyz
OpenRouter https://openrouter.ai/api
Custom (OpenAI-compatible) any endpoint that speaks the OpenAI chat-completions format

Kaptain adds /v1/chat/completions to the base URL unless it already ends in a version such as /v1. To replace keys later, use Settings › Runtimes › Providers & keys › Update keys: a blank field keeps the saved key.

Per-model settings#

The ⚙ next to the model picker opens Model settings for the selected model. Settings are saved per model and used from the next message. Revert to default clears every override for that model.

Setting What it does Values
Thinking Lets the model reason before answering, and shows it. Saves as soon as you click it. on or off
Stream tokens live Shows the reply as it is written, or only when it is done. on or off
Context window (num_ctx) The whole window: instructions, tools, history and room for the reply. The hint shows the default and the model's maximum. a number; empty uses the default
Max output (tokens) Caps the reply and keeps room for it in the window. a number; 0 uses the model's own cap
Tool approval What tools may do without asking. See Tools and approvals. Ask (default), Ask before risky actions (the same as Ask), Read-only, Auto-approve in workspace, Full access
Tool calls How the model is asked to call tools. Auto tries native tool calls and switches to a taught text format if the model writes calls as text. Auto, Native, Text protocol
Reasoning per step How much a local or cloud model may think before each step. Shown only for models that declare reasoning. Auto — sized from the room left in the window, No limit from Kaptain, or Fixed number of tokens
Reasoning effort Shown only when the model declares effort levels: CLI models, and cloud models added with reasoning ticked. the model's levels
Model CLI models only: the model the CLI runs. CLI default, or a model

A model on a paired machine shows Tool approval, Tool calls and Stream tokens live here, and nothing else: its thinking, context window and output cap are set on the machine that owns it, and Kaptain follows them. Its tool calls run on this machine, so the approval you choose here applies to them (a kapsule's Permissions still win in that kapsule). A lent Claude or Codex CLI is the exception: it runs its own tools on the other machine, under that machine's rules, and this panel says so (Pairing machines).

Images and vision#

When a turn includes an image and the chat model cannot see it, the vision_analyze tool hands the picture to a vision model and returns a description. Choose that model under Settings › Model Handling › Vision tool:

Thinking is Auto (no thinking first, then one retry with thinking if the answer comes back empty), Off or On, with answer budgets of 1,000 tokens without thinking and 2,500 with it. Images larger than 2,000 pixels on a side or over 5 MB are scaled down first; one that still does not fit in 5 MB is refused. A description may take up to 600 seconds; set KAPTAIN_VISION_TIMEOUT_S for a slower machine.

See your models from the terminal#

Terminal
$ kaptain models
claude-cli
codex-cli
gguf:Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf
gguf:gemma-4-12B.gguf
qwen3:4b
qwen3.5:9b
mistral:latest

The list is installed CLIs first, then cloud models, then GGUF files, then Ollama models. It also lists embedding models, which are not chat models. kaptain doctor checks everything a model route needs in one go:

Terminal
$ kaptain doctor
Kaptain environment check
  GPU:      vulkan (AMD Unknown (RADV RENOIR))
  llama:    /home/you/llama/llama.cpp/build/bin/llama-server
  uses:     Vulkan (Vulkan0: AMD Unknown (RADV RENOIR) (34192 MiB, 33720 MiB free)) → -ngl 999
  ollama:   reachable — 9 models (nomic-embed-text:latest, llama3.2:1b, qwen3.5:4b …)
  claude:  available (CLI harness, spawn: direct)
  codex:   available (CLI harness, spawn: direct)
  gemini:  not on PATH
  gguf:     5 local model(s) via llama-server
  shell:    /usr/bin/sh (posix, via default)
  probe:    cli_exec echo OK in 0ms

chat is ready for whatever is reachable above.

kaptain doctor --json prints the same as JSON. Doctor only reads: it installs and changes nothing. The uses: line says what llama.cpp runs on; -ngl 999 means every layer runs on the GPU. On a machine with no GPU the first line is GPU: cpu (CPU) and uses: ends in -ngl 0. Set KAPTAIN_GPU_LAYERS to override it.

Kapsules#

A kapsule is an agent you define as a folder: a model wrapped with a persona, a tool allowlist, a permission mode, skills, memory and an optional schedule. It has its own chat threads, its own jobs and its own workspace, and it ships as one reviewable kapsule.json file you can diff, copy and keep in git.

A kapsule is a harness, not just a prompt. The model decides how to think; the kapsule fixes what it may touch, how much it may do unattended, and what it remembers. When Can bring in workers is on, a kapsule may split a job across workers it creates for that job: each worker gets only the tools its part needs and never more than the kapsule itself, and a worker that provably completes its part is kept and reused.

Two kinds of agents#

Kapsule agent Worker
Defined by you, in kapsule.json a kapsule, while a job runs
Lifetime persistent born for one role in one job; kept only if it completed with evidence
Named by you by its role; earns a place in the kapsule's Workers list by succeeding
Reached from chat, a schedule, the terminal, other agents its own job
Powers bounded by the kapsule's permissions and allowlist never wider than the kapsule that made it

Create a kapsule#

Open Kapsules, press + New kapsule and fill in:

Field What it means
Name Letters, numbers, - and _. It names the folder and the tool other agents call (agent_<name>).
Purpose and Generate persona One line about the job; the button drafts a persona from it.
Persona The kapsule's instructions. Required; edit the draft freely.
Model Any model in the picker. Leave it on engine default to use Kaptain's default model.
Tools An allowlist. Nothing ticked means the whole catalogue, every call still approval-gated.
Schedule and Time On demand, every day at a time, or an interval. The time is your local time.
Standing task What each scheduled run does. A schedule without a task is refused.
Can bring in workers Lets the kapsule split a job across workers (above).
External paths Optional. Folders outside its workspace it may change: Add path adds one, and Add the project folder adds your project folder in one tap (What a kapsule may write).

You can also ask Kaptain chat to create or change a kapsule for you; it uses the agent-creation skill (Edit access). Create kapsule saves it and it is live at once. Permissions, skills, run memory, trusted scopes and delegation are set afterwards under the kapsule's Settings, where you can also change its folders. An on-demand kapsule has no standing task until you add one under Settings › Instructions, and Run now needs one.

Schedule a kapsule, step by step#

A kapsule that writes a short digest every morning, from nothing:

  1. Open Kapsules and press + New kapsule.
  2. Give it a Name, such as news-digest. Write one line under Purpose and press Generate persona, or write the Persona yourself.
  3. Choose a Model. A small local model is enough for a digest; leave it on engine default to use Kaptain's default model.
  4. Under Schedule, choose Every day at a set time and a Time in your local time, or an interval such as Every 6 hours.
  5. Write the Standing task, what every run does: "Write today's digest to digest.md in your workspace." A schedule without a task is refused.
  6. Press Create kapsule. It is live at once.
  7. Open its Settings › Model & permissions › Permissions and decide what an unattended run may do. On Ask a scheduled run stops at its first risky step, because nobody is there to answer; Auto-approve in workspace lets it change its workspace, and any folder you added under Edit access, without asking (What a kapsule may write).
  8. Press Run now to watch one run, then read it under Jobs and in BlackBox before you trust the schedule.

The file it writes is in its workspace, .kaptain/kapsules/news-digest/ in your project folder. To change a kapsule later, use its Settings, or ask Kaptain chat in plain words (Edit access).

Design a good kapsule#

Kapsule settings#

Under the kapsule's Settings:

Fold Setting What it does
Model & permissions Model, Enabled The model, and whether it runs at all
Permissions Inherit from model, Ask before risky actions, Read-only, Auto-approve in workspace or Full access. Travels with the kapsule file.
Remember previous runs, Reset run memory Run memory, off by default (below)
Schedule Runs On demand, daily at a time, every N hours, or every N minutes
Swarm Can bring in workers, Delegation Workers, and whether this kapsule may call other kapsules
Edit access Folders this kapsule may change, Can edit kapsules Its workspace, then every folder you listed for it (external paths and trusted scopes, one list), and the other kapsules it may change (below)
Trusted scopes one entry per line Folders it may change (rw) or read without asking (ro), MCP servers it may use without asking, and the web hosts it is limited to (below)
Tools the allowlist Ticking an agent_<name> tool lets it call that kapsule
Skills skill names Skills woven into its instructions on every turn
Instructions Persona, Task What it is, and what each run does
Danger Delete kapsule Moves it to agents_deleted/ in the data folder, where it can be recovered; the 20 most recent deletions are kept

Permissions for unattended runs. A scheduled run has nobody to answer a prompt; What a kapsule may write says where it can change files at all. On Ask, it stops at its first risky step and reports what it could not do. Auto-approve in workspace and Full access run without prompts. For a Claude or Codex kapsule, Full access is the only mode that runs to completion unwatched. On a local or cloud model, the kapsule's mode replaces the model's; on a CLI model whose own approval you set, the stricter of the two applies, so a kapsule can never widen what you allowed the CLI.

Trusted scopes#

Trusted scopes name targets, never whole tools. Write one per line under the kapsule's Settings › Trusted scopes:

Trusted scopes
path:/home/you/reports rw
path:/home/you/reference ro
mcp:mcp-github
host:news.ycombinator.com

This kapsule can never change its own definition (kapsule.json and its files), even inside a folder you granted — edit it from Settings or Kaptain chat.

Letting a kapsule edit files outside its workspace, or other kapsules#

Only the kapsule's workspace is allowed by default. Any other folder needs to be added, the project folder too. A kapsule changes files only in its workspace and in the folders you list for it; each listed folder includes everything under it. You list them under the kapsule's Settings › Edit access, in one list:

Setting What it does
Folders this kapsule may change Its workspace first, always, with no Remove. Then every folder you listed, each row saying where it came from: External path or Trusted scope (a path:<folder> rw trusted scope). Both are the same grant. Remove takes a folder off, from wherever it was stored. Add folder adds a box for one absolute folder, kept as an external path. Add the project folder (<path>) adds your current project folder in one tap. Press Save edit access to keep the changes.
Can edit kapsules The other kapsules this one may change: their definition (task, tools, model, schedule, folders) and the files in their workspaces. Empty by default.

A folder is refused when you save, with the reason, when it is not absolute, does not exist, is / (the whole computer), is inside Kaptain's data folder, or is inside another kapsule's workspace that is not ticked under Can edit kapsules. A folder that holds Kaptain's data folder or other kapsules' workspaces (your home folder, the project folder) is allowed: the data folder and those workspaces stay closed inside it. If a listed folder is deleted later, the kapsule's next run says so and leaves it out.

Schedules and run memory#

Write Means
(empty) On demand only: chat, Run now, the terminal, or another agent
daily@08:30 Every day at 08:30 in the kapsule's time zone
every 6h@08:00 Every 6 hours on fixed slots counted from 08:00: 02:00, 08:00, 14:00, 20:00
30m, 1h, 90m Every interval after the last run, with no clock anchor

Run memory is off by default. Each scheduled run starts fresh from its task, the way you would brief a person. Replaying past runs compounds: one bad run steers the next, old evidence reads as current, and the window fills with yesterday. Turn Remember previous runs on only when a job builds on its own last answer, such as a tracker that must know what it already reported. Reset run memory clears a run history that went wrong. Separately, a kapsule can keep short lessons with the remember tool: one-sentence rules kept only when a run finishes cleanly, written to kapsules/<name>/<name>_workspace/guidelines.md in the data folder, where you can read and edit them and the kapsule can only read them. Resetting run memory does not clear lessons.

Agents calling agents#

By default an agent cannot call another. A kapsule may call another when:

Off refuses every call, whatever else is set. Calls nest at most three deep, and a loop is refused. Claude and Codex models reach agents through the agent_list and invoke_agent tools instead. Whatever one agent passes to another is material to work on, never an instruction with the caller's authority.

kapsule.json#

Each kapsule's definition lives in kapsules/<name>/ in the data folder, and its workspace in the project folder:

Folders
<data folder>/kapsules/<name>/kapsule.json                     the definition
<data folder>/kapsules/<name>/<name>.md                        optional persona file, used when "system" is empty
<data folder>/kapsules/<name>/<name>_workspace/guidelines.md   its lessons, kept by Kaptain
<project>/.kaptain/kapsules/<name>/                            its workspace: the files it makes and keeps

The definition folder is read-only to the kapsule. The workspace is made on the kapsule's first run, with a README.md saying what it is; files an older Kaptain kept in <name>_workspace/ are copied into it once, and nothing is deleted. To put the workspace elsewhere, set workspace in the kapsule's agent block, or kapsule_workspace_dir in kaptain.json for every kapsule (it must contain {name}; {project} and {name} are filled in, and a leading ~/ is your home folder). A workspace inside the data folder is refused.

The smallest valid kapsule:

kapsule.json
{ "name": "notes", "agent": { "system": "You keep tidy meeting notes." } }

A fuller one:

kapsule.json
{
  "name": "news-digest",
  "agent": {
    "name": "news-digest",
    "system": "You write a short morning digest of AI news.",
    "model": "qwen3:8b",
    "tools": ["web_search", "web_fetch", "file_write", "time_now"],
    "skills": ["house-style"],
    "max_rounds": 8,
    "task": "Write today's digest to digest.md in your workspace",
    "schedule": "daily@08:30",
    "schedule_tz": "America/Toronto",
    "approval_mode": "auto",
    "memory": false,
    "trusted_scopes": ["host:news.ycombinator.com"],
    "delegation": { "mode": "off" }
  }
}
Field Meaning Default
name The kapsule's name the folder name
enabled (top level) false hides the whole kapsule true
agent / agents One agent, or a list of agents in one folder
agent.system The persona <name>.md
agent.model A model id as the picker shows it: an Ollama name such as qwen3:8b, gguf:<file>.gguf, cloud:<id>, claude-cli, codex-cli, or node:<machine>/<model> Kaptain's default model
agent.tools The allowlist; empty means the whole catalogue empty
agent.skills Skill names injected every turn none
agent.task, agent.schedule, agent.schedule_tz The standing task and when it runs on demand
agent.approval_mode ask, sandbox (Read-only), auto, full, or empty to inherit the model's inherit
agent.memory Run memory off
agent.max_rounds Tool rounds per run 50
agent.trusted_scopes Trusted scopes; its rw folders are folders it may change none
agent.external_paths Absolute folders outside its workspace it may change; one list with its rw trusted scopes (Edit access) none
agent.can_edit_kapsules Other kapsules it may change (Edit access) none
agent.swarm Can bring in workers false
agent.delegation { "mode": "auto", "allow_agents": [...] }; the mode is "off", "auto" or "aggressive" see above
agent.use_kapsule_tools Also grant every tool of this kapsule's own MCP server false
skills (top level) { "paths": ["./skills"] }: skill folders shipped with the kapsule none
mcp (top level) { "command": ["./server"], "env": {}, "dir": "" }: the kapsule's own MCP server none

Kapsules created or changed in the Kapsules view apply at once. A kapsule.json you add or edit by hand is read the next time Kaptain starts, and a kapsule's own mcp server and skills folders are loaded at start. The Kapsules view edits single-agent kapsules; a kapsule with an agents list is edited in its file.

From the terminal#

Terminal
$ kaptain agent list
news-digest          model=qwen3:8b             enabled  schedule=daily@08:30
notes                model=                     enabled  schedule=on-demand
Command What it does
kaptain agent list Every kapsule agent with its model, state and schedule
kaptain agent run <name> "<task>" One turn with that agent's persona and memory, without tools. Use the web interface for runs that need tools.
kaptain agent chat <name> "<message>" One turn of the agent's direct chat, which remembers the conversation
kaptain agent history <name> Prints that direct chat
kaptain agent enable <name>, kaptain agent disable <name> Pauses or resumes an agent without editing its file
kaptain agent set-model <name> <model> Changes its model from the next run

Skills#

A skill is a Markdown document a model loads when it is relevant: a checklist, a runbook, your house style. Models see each skill's name and one-line description, and load the full text only when they need it.

skills/deploy-runbook/SKILL.md
---
name: deploy-runbook
description: Exact steps and checks for deploying the storefront.
---
# Deploy runbook
1. Run the test suite …

A skill is a folder with a SKILL.md (scripts and files beside it are kept) or a single <name>.md. Without a name, the folder or file name is used; without a description, the first line of text.

Where skills come from#

When two skills share a name, the first source in this list wins:

  1. The project: .kaptain/skills, .claude/skills and .agents/skills in the project folder. These follow the project as it changes.
  2. This machine: skills/ in the data folder, where the Krew view and kaptain skill add put them.
  3. Kapsules: the skill folders a kapsule ships with.
  4. Your CLIs: ~/.claude/skills, ~/.codex/skills (and the skills of Codex plugins you enabled) and ~/.gemini/skills are offered only when that CLI is the model answering, so they do not appear in Krew › Skills or in skill_list; ~/.agents/skills is shared with every model.
  5. Imported folders listed in KAPTAIN_SKILL_IMPORT_ROOTS.
  6. Kaptain's own: skills built into Kaptain, such as agent-creation.

Add a skill#

Terminal
$ kaptain skill add ./release-notes-skill
installed  release-notes                1 file(s) → /home/you/.local/share/kaptain/skills/release-notes/SKILL.md
$ kaptain skill list
release-notes                    global       Draft release notes from a git log range.

kaptain skill add takes a folder, a .zip, a git URL or owner/repo, and refuses to overwrite a skill of the same name unless you add --replace. kaptain skill list --harness claude adds that CLI's own skills.

How models use skills#

Tools, approvals and safety#

What a model may do on your computer is decided by five things, and all five are yours to set:

  1. Whether it has tools at all. In Chat, Tools is off until you turn it on. A kapsule run always has tools, limited to its allowlist.
  2. Its approval mode (below): Ask, Read-only, Auto-approve in workspace or Full access.
  3. Where it may write. The project folder, a kapsule's own workspace, and folders you name. Never Kaptain's data folder, and never a kapsule's own definition (What a kapsule may write).
  4. Sudo, which is one switch, and every sudo shows you a pop-up (below).
  5. Which MCP servers are connected; their tools pass the same gate (MCP).

Krew is Kaptain's toolbelt: everything a model can do besides talk. A model gets tools when Tools is on in the chat, or always in a kapsule run. Every tool has its own switch under Krew › Native Tools, and nothing is off by default. A tool a kapsule lists explicitly stays available to that kapsule even when its global switch is off.

Family Tools
Code search (KodeGraph) kodegraph_explore, kodegraph_context, kodegraph_search, kodegraph_node, kodegraph_callers, kodegraph_callees, kodegraph_impact, kodegraph_files, kodegraph_status, kodegraph_index
Files file_read, file_search, file_write, file_edit, patch_apply
Shell cli_exec, test_run, git_op
Web web_search, web_fetch, web_fetch_raw, web_extract
Skills skill_list, skill_load
Memory remember, session_recall, tool_result_recall
Workflow todo, time_now, ask_user
Delegation delegate, delegate_batch, assemble, delegate_status
Vision vision_analyze
Agents agent_cards (workers), kapsule_create, kapsule_edit, and one agent_<name> per kapsule

The Krew tools reference has one entry per tool: what it does, when a model uses it, its permission and its parameters.

How tools reach the model#

When Tools is on, a local or cloud model is not handed every tool's full description. A few are defined in full: file_read, file_search, file_edit, file_write, cli_exec, kodegraph_explore, tool_result_recall, todo and ask_user, plus every tool a kapsule names. The others are listed one line each under "Other tools available", and the model fetches the descriptions it needs with tool_schema_resolve before calling them. A listed tool called straight away runs when its arguments are right; otherwise its description comes back with the error, so the next call can be right. There is no switch: this is how tools work in every chat. Claude and Codex get Kaptain's tools through their own MCP connection instead.

Earlier results come along. Tool results have their own share of the window (When a tool result is too big). The chat's last 5 tool calls, with their results, are passed along whole into your next messages, within a quarter of the window, so a follow-up question is answered from what the model already read instead of reading again. When fewer fit, the newest that fit are kept and older ones are read by id with tool_result_recall. tool_result_tail_calls in kaptain.json changes the 5, up to 32. Within a turn, the same read repeated is answered with a pointer to the result the model already has, until something may have changed it, such as an edit or a command.

Approval modes#

Every tool call that could change something passes one approval gate. Each model has a mode, and each kapsule can set its own:

  1. For a model: open the ⚙ next to the model picker and choose Tool approval. It applies from the next message, for that model.
  2. For a kapsule: open the kapsule's Settings › Model & permissions › Permissions. Inherit from model uses the model's mode. The choice is saved in its kapsule.json as approval_mode.
Mode (kapsule.json value) Local and cloud models Claude Code Codex
Ask (default), also listed as Ask before risky actions (ask) Kaptain pops up Permission required — "Kaptain is paused until you decide." — with Review tool input, Deny and Allow once, and the turn waits default mode, asking through Kaptain untrusted, workspace-write
Read-only (sandbox) Every change is refused, and the model is told "User denied the operation" plan mode read-only sandbox
Auto-approve in workspace (auto) Changes run without asking accept edits on-request, workspace-write
Full access (unrestricted) (full) Changes run without asking bypass permissions full access

The two Ask entries behave the same. Allow once applies to that one action only. Questions a model asks you appear in every mode.

For local and cloud models, Auto-approve and Full access behave the same; they differ for the CLIs, which have their own permission systems. Whatever the mode:

An approval waits 300 seconds once shown. When a run is unattended and nobody can answer, the model is told so, rather than told you refused, and it does what it can without that step.

Long commands and background jobs#

cli_exec gives a command 30 seconds unless the model asks for more, up to 300. For a local or cloud model, a command still running at its limit is not stopped: it carries on in the background as a job, and the model gets the output so far and the job's id, so it can wait for it, read new output or stop it. A model starts a server or watcher with background: true, which has no time limit. A process a command leaves running, such as a server started with &, is kept as a job as well, so nothing runs unseen.

Jobs show in a strip above the message box, such as "1 running in the background", each with how long it has run, its last line of output and Stop. A job ends when it finishes, when you or the model stop it, when its chat is deleted or when Kaptain stops; a command that outran its limit is also stopped after shell_job_max_minutes in kaptain.json (60 minutes; 0 means no limit). Jobs do not survive a restart, and one chat can have 8 running at once. Commands that Claude or Codex run through Kaptain's tools still end at their time limit.

What a kapsule may write#

Trusted scopes and external paths are how you give a kapsule write access. A kapsule granted a folder works there the way its approval mode allows: Full access or Auto-approve, it does it; Ask, it asks you first; Read-only, it refuses. The one thing it never edits is its own definition. Its file tools decide every write in this order, and the first rule that matches wins:

The path is The write is
Its own definition: kapsule.json and its files in Kaptain's data folder refused, in every mode, even inside a folder you granted: "this kapsule can never change its own definition (kapsule.json and its files), even inside a folder you granted — edit it from Settings or Kaptain chat"
Anywhere else in Kaptain's data folder, other kapsules' definitions included refused, in every mode
Another kapsule's workspace refused, unless that kapsule is ticked under Can edit kapsules
A folder you listed for it, an external path or a rw trusted scope, the project folder included once you list it allowed, under its approval mode
Its own workspace, .kaptain/kapsules/<name>/ in the project allowed, under its approval mode
Anywhere else, the project folder too refused (path_not_allowed)

Only the workspace is allowed by default; any other folder needs to be added. The kapsule still reads your project; it changes project files only after you add the project folder under Settings › Edit access › Folders this kapsule may change (Add the project folder does it in one tap). Kaptain chat, your own session, is not a kapsule and writes in the project as before.

In Read-only, every write is refused, even in its workspace. A kapsule never edits its own definition: changing its own task, tools, model, schedule or reach through kapsule_edit is refused as self_edit_refused, and writing its kapsule.json or another file in its definition folder is refused as definition_read_only; both are written to the Brain Log. You change a kapsule from its Settings, or ask Kaptain chat. The refusals the model reads say what to do instead, and a refused write is written to the Brain Log too, for example:

Output
refused: path_not_allowed — /home/you/project/notes/todo.md is outside every folder this kapsule may change — add it under Settings › Edit access › Folders this kapsule may change (the project folder /home/you/project is writable for a kapsule only when it is listed there: "Add the project folder" adds it). This kapsule may change files only in its workspace /home/you/project/.kaptain/kapsules/digest; nothing was changed

To let a kapsule change any folder besides its workspace, the project folder included, add it under Settings › Edit access › Folders this kapsule may change (Edit access), or write path:<folder> rw in its trusted scopes; both land in the same list and both follow its approval mode.

Shell commands and delegated files follow the same list. A kapsule's cli_exec and test_run run in its workspace unless you give them a folder it may change. A command that runs in, or names, any other folder is refused the same way (path_not_allowed, or not_permitted for another kapsule's workspace) and written to the Brain Log; a command that only reads, such as ls or cat, may look anywhere. A git_op that changes the repository needs the project folder in the kapsule's folders, and git started from its workspace does not reach the project's repository. This check reads the paths a command names; it is not an operating-system sandbox, so a script can still write where its own code decides. A file that delegate, delegate_batch or assemble writes takes the same decision as file_write, for a kapsule and in Kaptain chat alike: never in the data folder, on Ask you are asked before the model runs, and in Read-only it is refused.

Add your own tools#

A tool is a program that speaks MCP, in any language. There are three supported ways in, and all three land in the same catalogue, behind the same switches and the same gate:

  1. Connect it as an MCP server in Krew › MCP Servers or with kaptain mcp add (MCP).
  2. Ship it inside a kapsule with the kapsule's mcp entry, so the tools, the agent and its skills travel as one folder.
  3. Drop an executable into plugins/ in the data folder. Kaptain registers it at start and runs it as <program> mcp.

There is deliberately no way to paste a shell script as a tool: tools are real programs behind a real protocol, so they can be reviewed, versioned and gated.

MCP#

MCP works in both directions. In: any MCP server's tools join Kaptain's catalogue, for every model. Out: Kaptain's own toolbelt is an MCP server named kaptain-engine that Claude Code, Codex and other MCP clients can use.

Connect a server#

Install the server's own runtime first (for example Node for npx servers, or Docker for a server shipped as a container). Then, in Krew › MCP Servers:

Each row shows the server's status and tool count, with Enable or Disable, Reconnect, Edit, Remove and Sign in where it applies. A server that failed shows an (i) that opens the reason and the last lines it wrote. A value copied from a README example, such as {path/to/storage.json}, is pointed out on the row; Edit changes the command, arguments or address and keeps your stored keys. A removed server leaves the list at once. Connected tools appear in Native Tools with their own switches. From a terminal:

Terminal
$ kaptain mcp add tavily --env 'TAVILY_API_KEY=${TAVILY_API_KEY}' -- npx -y tavily-mcp
added tavily (stdio)
  Kaptain is not running; it will connect on next start
$ kaptain mcp add linear --url https://mcp.linear.app/mcp --oauth
added linear (http)
  Kaptain is not running; it will connect on next start
$ kaptain mcp list
linear               http   enabled  https://mcp.linear.app/mcp · oauth
tavily               stdio  enabled  npx -y tavily-mcp
Command What it does
kaptain mcp add <name> [flags] -- <command> [args…] A local server. Flags: --env K=V (repeatable), --transport with stdio, http or sse, --oauth
kaptain mcp add <name> --url <url> [flags] A remote server. Flags: --header K=V (repeatable), --transport with http or sse, --oauth
kaptain mcp add-json [file] Adds every server in a {"mcpServers": {...}} block, from a file, or from standard input with - or no file
kaptain mcp list [--json] Your servers
kaptain mcp enable <name>, disable <name>, remove <name> Turns one on or off, or removes it

Warning

Keep the single quotes around ${VAR}. Kaptain stores ${VAR} and reads the variable from its own environment each time the server connects, so the secret never lands in its config file. Without quotes your shell replaces it first and the real key is saved.

Servers are saved in mcp_servers.json in the data folder, in the same shape as the README blocks, so you can also edit it by hand. A Kaptain running in Localhost only mode picks up a change from kaptain mcp immediately. In Tailscale mode the command cannot reach Kaptain on this machine's local address, so it says Kaptain is not running even when it is; the change applies at the next start, as it does when Kaptain is stopped. OAuth tokens are kept in their own file, never in mcp_servers.json, and the interface shows key names, never values. A local command that is not installed is refused before anything is saved.

Tools from MCP servers pass the same approval gate as built-in tools and ask on every call in Ask mode. Connect only servers you trust.

Worked example: GitHub#

GitHub publishes its MCP server as a container, ghcr.io/github/github-mcp-server, which reads a personal access token from GITHUB_PERSONAL_ACCESS_TOKEN. Kaptain keeps the token out of its files by reading it from its own environment.

  1. Install Docker and check that docker run hello-world works for your user.
  2. Make a token on github.com under Settings › Developer settings › Personal access tokens, with only the access you want models to have. GitHub's README names repo, read:packages and read:org as the scopes it uses.
  3. Start Kaptain with the token in its environment. In the terminal you start Kaptain from, read the token without showing it, then restart:
    Terminal
    $ read -rs GH_PAT
    $ export GH_PAT
    $ kaptain stop
    $ kaptain start
    kaptain start passes its environment to Kaptain. Put the two lines in your shell profile, or a file only you can read, if Kaptain should always have it.
  4. Add the server. In Krew › MCP Servers, press + Add from JSON and paste:
    GitHub MCP server
    {
      "mcpServers": {
        "github": {
          "command": "docker",
          "args": ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
          "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GH_PAT}" }
        }
      }
    }
    Kaptain saves ${GH_PAT} as written and fills in the value each time it starts the server.
  5. Check it. The github row shows its status and tool count, and its tools appear under Krew › Native Tools with their own switches. In Chat, turn on Tools and ask "List the open pull requests in <owner>/<repo>". On Ask, each GitHub call shows Permission required first.
  6. Let a kapsule use it without prompts, if you want: add mcp:mcp-github to the kapsule's trusted scopes.

The same from a terminal, with the block saved as github.json:

Terminal
$ kaptain mcp add-json github.json
added github (stdio)
  Kaptain is not running; it will connect on next start
$ kaptain mcp list
github               stdio  enabled  docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

If the row shows the server failed, its (i) opens the reason and the last lines the server wrote; an unset GH_PAT or a token GitHub refuses shows up there.

Sign in with OAuth#

A hosted server that uses OAuth needs no key in Kaptain: you approve Kaptain in the vendor's own page, and Kaptain keeps the token in mcp_oauth.json in the data folder, readable only by you.

  1. In Krew › MCP Servers, press Add manually. Give it a name, the server's Remote URL, and under How does this server authenticate? choose OAuth — sign in after adding. From a terminal: kaptain mcp add <name> --url <url> --oauth.
  2. On the server's row, press Sign in. A new tab opens the vendor's page asking you to approve the connection.
  3. Approve it. The tab then goes to a local address that does not load; that is expected.
  4. Back in Kaptain, Finish signing in to <name> asks for the Redirected URL (or just the code). Copy the whole address from that tab's address bar, paste it, and press Complete sign-in.
  5. The row now says signed in, and Sign out removes the token.

If the vendor needs an app of your own first, step 2 opens Sign in to <name> asking for the Client ID from the vendor's OAuth app; enter it and press Continue. Kaptain refreshes the token by itself; when it can no longer be refreshed or the server refuses it, the row shows Sign in again, and tools from that server answer with a sign-in hint until you do.

Kaptain as an MCP server#

kaptain mcp runs Kaptain's toolbelt as an MCP server over stdio, named kaptain-engine.

Inside Kaptain there is nothing to set up: when Claude Code or Codex is the model, Kaptain attaches kaptain-engine to every turn with the chat's project, approval mode and grants. Your connected MCP servers are passed through to them too, as ext__mcp-<name>__<tool> (or ext__kapsule-<name>__<tool> for a kapsule's own server).

Outside Kaptain, in your own terminal or editor, a CLI needs kaptain-engine in its own configuration. Use Register standalone in the CLI model's ⚙ settings, or:

Terminal
$ kaptain mcp register claude
$ kaptain mcp install-status claude
CLI What register writes Check from the CLI
Claude Code claude mcp add -s user kaptain-engine -- <kaptain> mcp, or the entry in ~/.claude.json claude mcp get kaptain-engine
Codex [mcp_servers.kaptain-engine] in ~/.codex/config.toml codex mcp list
Gemini CLI mcpServers.kaptain-engine in ~/.gemini/settings.json

Every file change keeps a backup beside the file as <file>.kaptain.bak, and a config that does not parse is never overwritten. kaptain mcp unregister <cli> removes exactly what Kaptain added. After kaptain update, run register again if the CLI reports the server missing; it is safe to repeat.

Registered this way, outside Kaptain, kaptain-engine offers Kaptain's reading tools: code search, reading and searching files, read-only shell commands, web lookups and skills. Tools that change files or run other commands are refused with "User denied the operation", because there is no Kaptain approval prompt in that setup. It also cannot find a running Kaptain from outside: agent_list reads your kapsule folders directly, invoke_agent answers that it cannot reach the Kaptain engine, tools from your connected MCP servers do not appear, and sudo is refused, because its pop-up needs Kaptain. For the full toolbelt under your approval mode, use the CLI as a model inside Kaptain.

Check the server:

Terminal
$ kaptain mcp smoke
kaptain MCP smoke passed (/home/you/.local/bin/kaptain)
$ kaptain mcp health
Output
{
  "ok": true,
  "server": "kaptain-engine",
  "version": "<version>",
  "tool_count": 42,
  "sample_tool": "kaptain_models",
  "sample_ok": true,
  ...
  "detail": "kaptain-engine MCP healthy — 42 tools, kaptain_models returned a live result"
}

kaptain mcp health exits non-zero when the server is unhealthy, so it can run in scripts. The 42 tools, with every Krew switch on, are the 38 Krew tools plus four that exist only on this server: kaptain_models, kaptain_chat, agent_list and invoke_agent.

Delegation and token use#

Delegation lets the model in your chat hand bounded, mechanical work, such as summaries, extraction, boilerplate or log digests, to a second model, the worker, while it keeps the conversation and the final judgement; the worker can be any model, and a local one's tokens cost nothing. Choose it under Settings › Model Handling › Delegation › Worker model and press Save (there is none until you do, and the delegate tools answer "no worker model chosen — pick one in Settings ▸ Delegation"), then turn on Tools and Delegate in the chat: the model decides when a piece of work suits the worker, or you ask outright. A worker without tools has its result checked for quality, so a failed check comes back as a failure, never as substituted text; a worker given tools reports output_written true only when the file it was asked to write really changed. Most of what a model is billed for is not your question but everything resent around it, the history, earlier tool results and the instructions, so Kaptain cuts cost by mechanism rather than by picking a cheaper model: KodeGraph hands the model the code that matters instead of whole files, compaction folds old history into a summary, scheduled runs start fresh from their task, tools are described in full only when a model needs one, and big results are read by id instead of resent; see what you spent in BlackBox › Model usage, or with kaptain usage for Claude and Codex.

Observability#

Unattended agents are only trustworthy if you can see afterwards exactly what they did and what it cost.

BlackBox#

Session turns lists recent turns, for This session or All sessions, so a run at 3 a.m. is as inspectable as your live chat. Open a turn to see:

In the chat itself, each turn's context card, What <model> received, says in plain words what the model was handed: Kaptain's standing instructions, the earlier messages and any summary, the tools (ready to use, or listed by name), the room for tool results, the model's memory and the tool history carried along. Developer details (i) holds the raw numbers. Each turn opens with its trace record. A kapsule's turns also show inline in its own chat. Model usage shows provider-reported tokens with totals for today, the last 7 days and this month, and the plan allowance of your Claude or Codex subscription.

Traces#

Every run leaves one trace record, however it started: your chat, a message to a kapsule, a scheduled or invoked kapsule run, a channel message, a swarm card or a delegate worker. The record looks the same wherever you open it: a turn in BlackBox › Session turns, the trace under an answer in a kapsule's chat, and a run in Kapsules › Traces or Jobs. It shows:

Your message reaches the model exactly as you typed it. What Kaptain knows about a run goes in About this run, never into your words. A conversation is told the hour, so its cached instructions change at most once an hour; a scheduled run or a worker, with nothing after its instructions but its task, is told the minute. To have the send time stamped at the end of each of your messages instead, set turn_time_stamp to message in kaptain.json.

The record keeps sizes and fingerprints, never text: the text stays in the chat's own history, which View and Result read. A delegate worker has no history of its own, so its record holds sizes only. A run without a record says why: it ran before 0.0.9, or its record has expired. Deleting a chat deletes its runs' records. Messages about Kaptain's own health stay in Brain Logs.

God's Eye and KodeGraph#

KodeGraph indexes your project into a graph of files, symbols and calls, stored in .kodegraph/ inside the project. Models query it with the kodegraph_* tools instead of reading whole files. It re-indexes changed files every two minutes in the background (a home folder is never re-indexed automatically). Semantic search uses the embedder chosen under Settings › Model Handling › KodeGraph Embedder. Automatic (recommended), the default, uses Kaptain's built-in model if it is already running, else an embedding model already installed in Ollama, else the built-in model (Start Kaptain). You can also pick the built-in model, an Ollama embedding model, a GGUF embedding file on this machine, None (keyword search only) or Custom endpoint…. With None, or while no embedder can be reached, it ranks by keywords.

God's Eye (spelled Gods Eye in the interface), under Views, draws that graph: search symbols, open the file atlas, and inspect a symbol's callers, callees and impact. Build index indexes on demand. The same queries work from a terminal:

Terminal
$ kaptain kodegraph index
$ kaptain kg status
Output
Project: ~/project (kaptain.json project_dir)
{
  "call_edges": 1,
  …
  "files": 1,
  …
  "index_status": "ready",
  …
  "ok": true,
  …
  "root": "/home/you/project",
  "stale": false,
  …
  "store": "sqlite+fts5",
  "symbols": 2,
  "vectors": 0
}
Command What it does
kaptain kg index [--root DIR] [--confirm] Builds or refreshes the index of the current folder (--confirm allows a home folder or a very large tree)
kaptain kg status Index statistics. The project and where it came from go to the error stream first. The embedder in use is under Settings › Model Handling › KodeGraph Embedder.
kaptain kg search "<name>" [--kind K] Finds a symbol; K is function, method or class
kaptain kg node "<symbol>" One symbol with its source
kaptain kg callers "<symbol>", callees "<symbol>" Who calls it, and what it calls
kaptain kg impact "<symbol>" Everything affected if it changes, three levels deep
kaptain kg context "<task>" [--budget N] The code relevant to a task, within a token budget
kaptain kg ensure-embedder Pulls nomic-embed-text into Ollama when Ollama has no embedding model

kaptain kg is short for kaptain kodegraph. Output is JSON.

Brain Logs#

Brain Logs shows Kaptain's own activity as it happens: compaction, models loading and unloading, tool and delegation events, MCP servers. Filter by errors, brain, local or tools. The server's process log is a separate file, kaptain.log in the data folder.

Token usage from the terminal#

kaptain usage reads the Claude Code and Codex session records on this machine and prints token totals per session. It covers every session of those CLIs on the machine, inside Kaptain or not. Local and cloud model usage is in BlackBox › Model usage.

Terminal
$ kaptain usage
Output
TOTAL processed: 28282520 tokens  (in 1204311 · cacheRead 26943618 · out 134591)

PROVIDER SESSION                                 CALLS    PROCESSED
claude   0d5f2c1e-8a4b-4f0e-9c2d-6b1a7e3f9d10      412     18402113
codex    7a91b3c4-2d5e-4f6a-8b7c-9d0e1f2a3b4c      205      9880407

--json prints every session as JSON, and --watch streams updates.

Channels#

Channels let you talk to Kaptain from the messaging apps you already use. Each channel is your own bot, run from this machine, so no public address and no open port is needed. Kaptain 0.0.9 supports Telegram, Signal, Discord and Slack.

  1. Open Channels, choose an app and follow its steps, or run kaptain channels setup <app> for the same steps in the terminal. Telegram takes about five minutes with BotFather. Signal links Kaptain to your own account as an extra device, like Signal Desktop (Kaptain downloads its own Signal client, about 110 MB, once). Discord and Slack use your own bot or app.
  2. Message your bot. It answers with a pairing code, because it does not know you yet.
  3. Approve yourself in Channels, or with kaptain channels approve <app> <CODE>. Codes expire after 15 minutes.

Who a channel serves: Assistant answers only you and reads everyone else as context; Bot gives strangers a pairing code to request access. Groups are a second gate: add the bot to a group, mention it once, then allow that group.

Command What it does
kaptain channels list Available and connected channels
kaptain channels setup <app> Step-by-step setup for telegram, signal, discord or slack
kaptain channels pending, approved Who is waiting, and who can talk to Kaptain
kaptain channels approve <app> <CODE> Lets someone in, using the code from their pairing message
kaptain channels revoke <app> <user> Takes access away; the user is an id or @name
kaptain channels groups <app> Groups the bot has been mentioned in
kaptain channels allow-group <app> <chat-id>, deny-group … Lets the bot answer in a group, or stops it

Add --account ID to choose a connection when you have more than one. Messages that arrive through a channel are content to work on, never instructions carrying your authority. By default, an approval a channel turn needs is shown to you in the chat app for you to decide in Kaptain.

Configure

Settings reference#

Settings has four sections: General, Model Handling, Runtimes and Network Access. Each card saves on its own; unless a row says otherwise, a change applies immediately with no restart. A card with a longer explanation shows an (i) next to its title; press it to read the explanation. Per-model choices live in the ⚙ model settings, and per-agent choices in each kapsule. Settings are stored in kaptain.json in the data folder, apart from per-model settings and API keys, which are stored in models.db.

General#

Card Setting What it does Default
Project Directory Set & Index The folder Kaptain works in: Deview, God's Eye, KodeGraph and every model tool are rooted here. Setting it re-indexes in the background. The path must exist. the folder Kaptain was started from
Appearance Toggle light / dark Switches the theme for this view. The theme button in the header remembers your choice in this browser. your system's preference
Update Kaptain Check for updates, Update now Checks the published version; Update now downloads, verifies and swaps the binary. Restart Kaptain to run it. See Update and uninstall. checks when the card opens
Feedback & Support Email the Kaptain team, Report a bug Opens an email draft with your version filled in. Nothing is sent by itself.
Account & License Refresh entitlement, Open CHYNJ account, Subscribe / manage billing; under This computer, Sign in to register and Approve with a code Shows your plan, whether this computer is registered, your account and the trial's time left. The two This computer buttons register it without changing its access code (Register a machine). Always reachable, even when the licence has lapsed. See Licence and devices.

Model Handling#

Vision tool: which model looks at images for models that cannot. See Images and vision.

Setting Values Default
Vision model Automatic, or any model that can see images, a cloud model, a CLI, or a paired machine's model Automatic
Thinking Auto (off, then one retry with thinking if the answer is empty), Off, On Auto
Answer budget, thinking off 100 to 4,000 tokens 1,000
Answer budget, thinking on 100 to 8,000 tokens 2,500

Delegation: Worker model runs delegated briefs. Any chat model works; embedding models are not offered. There is no default: it reads Choose a model until you pick one and press Save, and delegation stays off until then. Saving the empty choice clears it. See Delegation.

Context & Compaction: how long chats on local and cloud models stay inside the model's window. Raw messages are never deleted; models can pull old ones back with the session_recall tool. Claude and Codex chats are not compacted by Kaptain, because each CLI manages its own context.

Setting What it does Values Default
Summarizer The model that writes the rolling summary the delegate worker, or any model the delegate worker
Handoff written by Who writes the digest when a chat moves off a CLI model to another model The CLI itself; the CLI with the summarizer as fallback; or any model The CLI itself
Compact after Summarize once this many new messages are not yet covered 2 or more 20
Always keep verbatim The newest messages that are never summarized at least 1, fewer than Compact after 2
Summary size Longest summary, in words 100 to 8,000 1,200
Compact inside long turns Lets a long tool-heavy turn summarize its own earlier steps and continue on or off off
Show detailed context events Full cards with ids and timings instead of one-line chips; this browser only on or off off

Compact this chat now runs the summarizer on the open chat. Embedding models are not offered as summarizer or handoff author. With no summarizer chosen, Kaptain uses the delegation worker, then a model on this computer (GGUF, then Ollama), then a model on a paired machine, then a cloud model; it never picks Claude or Codex unless you choose one here. If no model can write summaries, Kaptain folds the older messages into a text-only summary without a model, and the chat's context card says so.

KodeGraph Embedder: the model behind semantic code search.

Setting What it does Default
Embedding model Automatic (recommended) uses an embedding model already installed in Ollama, otherwise Kaptain's built-in model (nomic-embed-text v1.5, downloaded once; see Start Kaptain). You can also pick Kaptain's built-in model, an embedding model installed in Ollama, an embedding GGUF on this machine, None (keyword search only) or Custom endpoint…. Add a model… adds one. Switching re-embeds your index in the background. Automatic
Endpoint URL, Endpoint model For Custom endpoint…: any OpenAI-compatible or Ollama embeddings endpoint, and the model name it expects empty
Downloads Lets Kaptain download the built-in model automatically when it is needed on

Now serving and Kaptain runtime show what is in use. Install llama.cpp now appears when Kaptain's own runtime is missing.

Scheduled Agents & Local Models: Distinct local models running agent jobs at once, 0 to 16. When scheduled agents collide, local models beyond this number wait their turn instead of stacking in memory; runs that share a model, and cloud runs, are never held. 0 means the default of 2; set 1 on a machine where two models crowd your memory. Applies from the next scheduled run.

Sudo requests: Ask me for my password (on by default) means every sudo a model or CLI runs, including one inside a program it started, opens a pop-up and you decide. Off means sudo commands are not run and the model is told why. Remember a typed password within a task for sets how long the password is kept for later pop-ups in the same task: 2 minutes by default, 0 to type it every time, at most 30. Every sudo still shows a pop-up. See Approval modes.

Models: a read-only count of every model Kaptain can reach, by route.

Runtimes#

Card What it does
Ollama Runtime Shows whether Ollama is installed and running, who manages it, its version and the GPU it uses, with Start, Stop and Update where they apply, and Install Ollama for me on Linux when it is missing. Actions on a system service ask for your password once and never store it.
llama.cpp Runtime Shows the llama-server in use and the GPU. Start server and Stop server load or unload a GGUF model. Executable path with Save path sets a specific llama-server; Use auto-detect clears it. A saved path is used from the next load.
Toolchain Paths Kaptain reads your login shell's PATH, so commands models run find the same tools you do. Extra PATH directories adds folders it cannot find; Rescan re-reads the PATH. Applies immediately.
Agent Shell (Windows) Windows only. Which shell runs model commands: Install portable Git Bash (about 37 MB) or set Manual bash path. Without Git Bash, commands fall back to cmd.exe, with fewer tools available.
Providers & keys Whether the Claude CLI, Codex CLI, cloud models and local GGUF files are available. Update keys replaces cloud API keys; a blank field keeps the saved key.

Network Access#

Card Setting What it does Default
Connection Shows the address Kaptain serves on, the engine, and the GPU. Fix GPU access appears when a GPU is present but unusable.
Network Access Localhost only or Tailscale Who can connect. Needs a restart: the card says Saved — one restart to apply it and offers Restart Kaptain now. Tailscale cannot be chosen until it is installed and connected. See Network and remote access. Localhost only
Require an allowlisted Tailscale device for non-local access Admits only the tailnet devices you choose. Your own machine is always allowed. Changes to the list are staged until Save changes. off
Share models between your computers Lend models to, and borrow models from, your other Kaptains. See Pairing machines. off
New access code Current access code, New access code Makes a new access code after you type the current one; the old one and every other browser's pairing stop at once. The new code is shown once, with Copy. See Get a new access code.
Access log Refresh The last 200 requests: time, status, address, method, path and duration. Requests without credentials are marked unauth.

Settings without a screen#

A few settings are read from kaptain.json but have no control in Settings. Edit the file while Kaptain is stopped, then start it; the network keys below are also picked up within about 30 seconds while running.

Key What it does Default
allowed_hosts Extra host names the browser may use, such as a Tailscale name. See HTTPS over Tailscale. none
allowed_client_cidrs Extra client address ranges allowed to connect, for example a trusted proxy none
ollama_url Where Ollama listens http://127.0.0.1:11434
max_tool_rounds Tool round trips allowed in one turn 50
max_parallel_tools Read-only tool calls run at the same time, up to 8 4
approval_timeout_seconds How long an approval waits for you once shown 300
stall_timeout_seconds A turn with no model output and no tool progress for this long is stopped by the stall guard. KAPTAIN_STALL_TIMEOUT wins when set. 720 (12 minutes)
agent_turn_timeout_seconds How long one kapsule run, direct message to an agent or agent call may take 7200 (2 hours)
agent_run_memory Run memory for every kapsule that does not set its own off
shell_allow_project_tests Lets cli_exec run pytest, go build, go vet, go test and npm test without asking in Ask mode; the test_run tool still asks off
shell_readonly_extra Your own commands to treat as read-only in Ask mode none
shell_job_max_minutes How long a command that outran its time limit may keep running in the background; 0 means no limit 60
tool_result_window_percent The share of the model's window one tool result may use, 5 to 50 15
turn_results_window_percent The share all of a message's tool results may use together, 10 to 80 30
tool_result_tail_calls How many of the chat's most recent tool calls ride whole into the next messages, at most 32; a negative number carries none 5
turn_time_stamp Where a run's date and time go: brief (under About this run, your message unchanged) or message (stamped at the end of each of your messages). See Traces. brief
run_record_ttl_days How many days a run's trace record is kept 30
run_record_max_rows How many runs' trace records are kept at most; the oldest go first 20000

Warning

kaptain.json also holds this machine's credentials: the access code, the device key and account details. Do not share it, and never edit the keys you do not recognise.

Security model#

Kaptain's security comes from a few blunt decisions rather than subtle ones.

Network and remote access#

Kaptain has exactly two network modes, and neither reaches the internet: Localhost only, this machine, and Tailscale, your own tailnet.*

* Your network is yours

CHYNJ does not manage or warrant the security of your network, your devices or your Tailscale account. Kaptain uses the tailnet you set up and run; who is on it, and how it is secured, is up to you. The Terms of Service, which you accept before you download Kaptain and before your CHYNJ account is created, apply.

Mode Kaptain listens on Who can connect
Localhost only (default) 127.0.0.1:8810 Programs and browsers on this machine
Tailscale this machine's tailnet address, such as 100.x.y.z:8810 Devices on your own tailnet that know the access code. In this mode, this machine also uses the tailnet address; 127.0.0.1 is refused.

Reach Kaptain from your phone or another computer#

  1. Install Tailscale on the Kaptain machine and on the other device, and sign both into the same tailnet. On the Kaptain machine, tailscale ip -4 prints its 100.x.y.z address.
  2. Switch Kaptain to Tailscale: Settings › Network Access › Tailscale, or kaptain remote on in a terminal (below).
  3. Restart Kaptain: Restart Kaptain now in Settings, or kaptain stop, then kaptain start.
  4. On the other device, open http://100.x.y.z:8810 and enter the access code.

In Tailscale mode, start Tailscale before Kaptain. If Kaptain starts while Tailscale is down, it falls back to 127.0.0.1 and only this machine can reach it; start Tailscale and restart Kaptain, or switch back with kaptain remote off.

kaptain remote#

kaptain remote shows the current mode and checks whether this machine is ready for remote access. It changes nothing:

Terminal
$ kaptain remote
Output
  Remote access: OFF — Kaptain listens on 127.0.0.1 only

  ✓ Tailscale                  up, this machine is 100.x.y.z
  ✗ Setup complete             no access code yet, so anyone on your tailnet could complete setup and take over this box
  ✗ Device registered          this machine is not registered to your CHYNJ account
  ✗ Licence                    Your 3-day free trial has not started.
  ! MFA                        off — the access code alone opens a session from any tailnet device
  ! Device allowlist           off — every device on your tailnet may reach Kaptain

  Not ready yet — see the ✗ lines above.

kaptain remote on refuses while any ✗ check fails, and says how to fix each one:

Output

Remote access was NOT enabled. Fix these first:

  ✗ Setup complete
    no access code yet, so anyone on your tailnet could complete setup and take over this box
    → run `kaptain setup` first
  ✗ Device registered
    this machine is not registered to your CHYNJ account
    → run `kaptain device register`
  ✗ Licence
    Your 3-day free trial has not started.
    → run `kaptain license refresh` (or `kaptain license status` to see why)

It switches to Tailscale only when every ✗ check passes: Tailscale up, setup finished, the device registered to your account, and a current licence. A machine set up in the terminal with skip, or one whose registration failed, has no device certificate and fails the "Device registered" check: run kaptain device register first, or switch in Settings › Network Access, which does not run these checks. kaptain remote off always works:

Terminal
$ kaptain remote off
Output
  Remote access disabled. Kaptain will listen on 127.0.0.1 only.

  Restart Kaptain for this to take effect:
      kaptain stop && kaptain start

When it is already off: Remote access is already off — Kaptain listens on 127.0.0.1 only.

Add --json to any form for machine-readable output.

Pair a browser or the app#

A browser or app that reaches Kaptain without credentials sees Pair this browser with Kaptain. Enter the access code and press Connect. The browser stays paired for 14 days, or until the access code changes. When the code changes, every other browser pairs again with the new one; the browser that made the change stays paired. Scripts and other programs can send the code as Authorization: Bearer chynj_…. The pairing screen says where the code is saved: access-code.txt in the data folder, and kaptain status prints the path. If you deleted that file, the code is api_token in kaptain.json. To replace it, see Get a new access code.

Allow only some devices#

By default any device on your tailnet that knows the access code can connect. To narrow that, turn on Require an allowlisted Tailscale device for non-local access in Settings › Network Access, tick the devices that keep access, and confirm. Tailscale vouches for each device's identity. You can also type a machine name, a tailnet address, a Machine ID, or a Tailscale login, which admits every device that person owns. This machine is always allowed, and turning the lock off never needs confirmation.

The Access log card shows who reached this Kaptain. A burst of unauth entries from one address is usually an unpaired browser tab polling; pair it and it stops.

HTTPS over Tailscale#

Kaptain itself serves plain HTTP. Tailscale already encrypts traffic between your devices, but browsers only show HTTPS, and only allow some features, on an https:// address. Tailscale Serve gives Kaptain a trusted HTTPS address on your tailnet:

  1. In the Tailscale admin console, turn on MagicDNS and HTTPS Certificates. Note the machine's full name, such as kaptain-box.example.ts.net. The certificate's name is published in public certificate logs, so rename the machine first if its name is private.
  2. Keep Kaptain in Localhost only mode. Serve connects to Kaptain from this machine, which Tailscale mode refuses.
  3. Publish Kaptain on the tailnet: tailscale serve --bg 8810.
  4. Allow the name. Add it to allowed_hosts in kaptain.json. Kaptain picks it up within about 30 seconds:
kaptain.json
{
  "network_mode": "localhost",
  "allowed_hosts": ["kaptain-box.example.ts.net"]
}

Open https://kaptain-box.example.ts.net/ from a device on your tailnet and pair with the access code. Until the name is allowed, Kaptain answers 421 Misdirected Request ("Host header is not allowed"). The same applies to any machine name you type instead of the tailnet address. Tailscale renews the certificate itself.

Behind Serve, every request reaches Kaptain from this machine, so the device allowlist does not apply, rate limits are shared, and the access log shows 127.0.0.1 for everyone. Leave trust_forwarded_for off. Use tailscale serve, not Tailscale Funnel, which would expose Kaptain beyond your tailnet.

Pairing machines#

Two of your Kaptains can share models: lend a model from one computer and use it from another, over your tailnet. The lending machine must be in Tailscale mode, and both must be on the same tailnet.* The borrower runs inference on the lender's models over your tailnet; the lender's models appear in the borrower's picker under the lender's name, as node:<lender>/<model>, and work everywhere a local model does: chat, kapsules, delegation, the summarizer and the vision tool.

What crosses, and what does not. The conversation and tool definitions cross, because the lender's model has to read them. Chats, files, settings and approval decisions never do. When a borrowed model asks for a tool, the tool runs on the borrower's machine, under the borrower's approval gate. The lender's own model settings (context window, output cap, thinking) apply to its models.

Warning

A lent Claude or Codex CLI is different: it runs its own tools on the lender's machine. Kaptain labels these "runs work here" and warns when you include them in a code. They are lent only when Share my signed-in CLI harnesses (Claude, Codex) is on, or in My Kaptail mode.

Set up the lending machine#

  1. Switch Network Access to Tailscale and restart.
  2. In Settings › Network Access › Share models between your computers, turn on Let other computers use this one's models. Kaptain asks for this machine's access code.
  3. Choose who may connect: My Tailnet (any device Tailscale vouches for), Custom (only devices on your allowlist), or My Kaptail (only machines on the same licence; see the note below). My Kaptail is selected at first.
  4. Under Issue a token, choose what it may do (Use the models on this computer, Only see which models exist, or Use the models, and manage codes), when it expires (24 hours, 7 days, 30 days or never) and, optionally, which models it covers. Press Issue token; Kaptain asks for the access code again. Copy the kcat_… code. It is shown once.

Connect from the borrowing machine#

In Settings › Network Access, under Computers you can borrow models from, enter the lender's tailnet address and the kcat_… code and press Connect. Kaptain answers "Connected to <name> — N model(s) now in your picker." Run one small prompt on a borrowed model to confirm.

To end access, press Revoke next to the code on the lending machine. It takes effect immediately.

Note

My Kaptail proves both machines hold the same licence. In 0.0.9 that proof needs a licence key pasted on both machines, and the borrower must run kaptain nodes verify <lender address> in a terminal within the 10 minutes before connecting. For a connection made from Settings alone, use My Tailnet or Custom.

From the terminal#

Terminal
$ kaptain nodes status
Output
  cluster identity   off (peers see 404)
  mode               license
  can prove licence  NO — this box has no licence key; only tailnet/custom modes can work
  verified peers     0
Command What it does
kaptain nodes status This machine's sharing settings and verified peers. Needs Kaptain running.
kaptain nodes verify <host> Runs the identity handshake with another Kaptain.
kaptain nodes token <host> <kcat_…> Stores a code that machine issued you.
kaptain nodes models <host> Lists the models that machine lets you run.
kaptain nodes ask <host> <model> "<prompt>" Runs one prompt there and streams the answer.

A code never leaves the machine that stores it: each request carries a signature bound to that request, not the code itself. Add --json for machine-readable output.

Licence and devices#

How a computer gets registered#

  1. Create your CHYNJ account at chynj.ca, or in Kaptain's setup.
  2. On the computer, sign in to that account: in Kaptain's setup, or run kaptain device register in a terminal and approve the code it prints at chynj.ca/account.
  3. The computer registers as a device and takes one seat of your plan's device limit.
  4. CHYNJ issues the computer's licence, a signed lease that Kaptain renews on its own, and Kaptain starts working.
  5. If you remove a device, sign in on that computer again to register it again.

Note

A licence key alone never registers a computer. Signing in is always required.

The three things behind it#

Three separate things make Kaptain usable on a machine:

Thing What it is How you get it
Licence Your plan, attached to your CHYNJ account email Subscribe at chynj.ca/account, or start the 3-day trial
Device certificate Proof that this machine may use your licence Finishing the setup wizard while signed in, or kaptain device register
Entitlement A short-lived signed proof, refreshed in the background about every 4 hours Automatic once the machine is registered or on a trial

A licence key proves you bought a plan; the certificate proves this machine may use it; the entitlement lets Kaptain keep working through short network outages without phoning home on every request. The trial is 3 days, needs no card, and belongs to the machine: reinstalling does not restart it. Pro covers up to 5 devices. To free a seat, open chynj.ca/account and, under Devices using your license, press Sign out or Remove on a device. Sign out keeps the device listed under Revoked; on that computer Kaptain says "This computer was signed out of your licence on chynj.ca. Restore it there to use it again." Restore on its row lets that computer register again by signing in. Remove asks once, then takes the device off your account; Kaptain on that computer says it was removed and asks you to sign in to register it again. Each row shows the first characters of the device's fingerprint hash, which kaptain device status prints in full.

Creating a CHYNJ account, on chynj.ca, in the setup wizard or with kaptain setup, asks you to agree to the Terms of Service and Privacy Policy, and CHYNJ records which versions you agreed to, when, and where. Signing in to an account you already have asks nothing new. CHYNJ refuses accounts, trials and licence renewals from places Canadian sanctions law does not let it serve; chynj.ca/legal/availability lists them. The website, these docs and the downloads stay open to everyone.

Check where a machine stands#

Terminal
$ kaptain device status
Output
{
  "cert_id": "",
  "entitlement": {
    "message": "Your 3-day free trial has not started.",
    "ok": true,
    "status": "not_started",
    "trial": {
      "consumed": false,
      "is_active_license": false,
      "status": "not_started"
    },
    "type": "trial_not_started",
    "valid": false
  },
  "fp_hash": "9c1e4f0a7b2d6e83c5a1f9047d3b8e2a6f1c0d9b4e7a2c5f8d3b6e1a9c4f7d20",
  "ok": true,
  "registered": false
}

That is a machine that was never registered and never started a trial. fp_hash is this machine's fingerprint hash, the value the licence server knows it by: chynj.ca shows its first characters beside each device under Devices using your license, so you can tell which row is this computer. kaptain license status prints just the entitlement, and kaptain account status adds the signed-in account. All three only read local files. kaptain license refresh asks the licence server for a fresh entitlement and says why if it cannot.

Register a machine#

Use this on a machine set up from the terminal, after a skipped sign-in, after a device was removed on chynj.ca, or whenever the machine shows as unregistered. It needs an active plan, or a trial on a verified email. Registering keeps this computer's access code, so paired browsers and phones stay paired. There are two ways.

In Settings. Open Settings › General › Account & License. Under This computer, press Sign in to register and enter your CHYNJ email and password (and the 6-digit code if your account uses two-factor sign-in), or press Approve with a code and approve the code it shows at chynj.ca/account. The card then says Registered, with your plan.

In a terminal, on the Kaptain machine:

  1. Run kaptain device register. It prints how a computer gets registered, then a code and the address to approve it at, opens your browser (unless you add --no-browser), and waits. With Kaptain running, it uses the same flow as the Settings card.
  2. On any device, open chynj.ca/account, sign in, and approve the code. Codes expire after 15 minutes; run the command again for a new one.
  3. The command stores the certificate and the licence and prints This computer is registered (plan: pro). Its access code did not change.
Output
Approve this computer at chynj.ca/account with this code:
  Code: <XXXXXX-XXXXXX>
  URL:  <approval address>
Waiting for approval — the code expires at 14:32.
This computer keeps its access code: browsers and phones paired with it stay paired.
This computer is registered (plan: pro). Its access code did not change.

A computer that has no access code yet, because it never finished setup, gets one: the command prints it once after Device registered. Save this local access code; it is shown once: and saves it to access-code.txt in the data folder. A computer that was signed out on chynj.ca is not registered again: the command says "This computer was signed out of your licence on chynj.ca. Restore it on chynj.ca first, then register it." On a computer that is already registered the command prints the registration (plan, account, licence until) and asks This computer is already registered. Register again? [y/N] before it starts a flow; with --json, or when nothing can answer (piped input), it prints that state and exits 0 without starting one, unless you add --again. Nothing secret is typed into the command. --nickname NAME names the machine in the portal (the hostname by default), and --json prints machine-readable output.

When Kaptain answers 402#

A release build checks its entitlement on every request. When it cannot, the interface still opens, but its requests answer 402 Payment Required with entitlement_required, so chats, models and most settings fail to load. Settings › General › Account & License keeps working so you can fix it.

Message (in the 402, or from kaptain license refresh) Cause Fix
Your 3-day free trial has not started. The machine was never registered and no trial was started, for example after skipping sign-in in kaptain setup Sign in: run kaptain device register and approve the code at chynj.ca/account
Device entitlement has not been refreshed. The machine is registered, but has not fetched its entitlement yet, for example because it has been offline since Reconnect, then kaptain license refresh
entitlement lease expired No successful refresh for about a day: offline too long, or the refresh is failing Reconnect, then kaptain license refresh; its message says what is wrong
This computer was removed from your account on … Sign in to register it again. The device was removed on chynj.ca under Devices using your license Register it again: Sign in to register in Settings › General › Account & License, or kaptain device register (Register a machine)
This computer was signed out of your licence on chynj.ca. Restore it there to use it again. The device was signed out on chynj.ca Press Restore on its row at chynj.ca/account, then register the computer again: Sign in to register in Settings › General › Account & License, or kaptain device register
device entitlement is revoked The licence server marked this device's entitlement revoked, for example after it was signed out Restore it on chynj.ca, or sign in on that computer to register it again (How a computer gets registered)
entitlement is bound to a different device certificate The machine was registered again part-way kaptain license refresh
entitlement is bound to a different installation key The device key in kaptain.json changed or was lost Register again
trial entitlement is bound to a different installation fingerprint A machine on a trial that was never registered changed its hostname, or its data folder moved to another machine Restore the old hostname, or subscribe and register
entitlement is not valid yet The system clock is behind Fix the clock, then kaptain license refresh
Kaptain G1_beta_v0.0.7 is below the minimum safe version G1_beta_v0.0.8, so this computer's licence was not renewed. … This computer runs a Kaptain release older than the oldest one the licence server still renews, so it refused the renewal. Kaptain keeps working until its current entitlement runs out, within a day. Development builds and builds without a release version are never refused Update Kaptain: Settings › General › Update Kaptain, kaptain update in a terminal, or run the installer again (Update). Once the entitlement has run out, Settings answers 402 as well; use the terminal or the installer. Then kaptain license refresh
License or trial expired. The trial ended or the subscription lapsed Subscribe or renew in the portal, then kaptain license refresh
CHYNJ cannot offer accounts, trials or licences where you are connecting from… You are connecting from a place CHYNJ cannot serve under Canadian sanctions law, so the entitlement is not renewed See chynj.ca/legal/availability

A registered machine, on a paid plan or a trial, keeps working when you copy its data folder to new hardware: the certificate and its key travel in the folder. Only a trial that was never registered is tied to the machine's fingerprint, which includes its hostname.

Licence troubleshooting: the licence email went missing? Your key is always in the account portal under License (the email comes from [email protected]; check spam). "No license found" means the licence is on a different email. "Device limit reached" means freeing a seat first: Sign out or Remove an old device on chynj.ca. "Invalid key" usually means stray spaces: use the portal's Copy button.

Files and environment#

The data folder#

Linux

~/.local/share/kaptain/

macOS

~/Library/Application Support/Kaptain/

Windows

%LOCALAPPDATA%\Kaptain\, which is C:\Users\<your name>\AppData\Local\Kaptain\. AppData is hidden: run explorer $env:LOCALAPPDATA\Kaptain in PowerShell, or paste %LOCALAPPDATA%\Kaptain into Explorer's address bar. This is the data, not the program, which is in %LOCALAPPDATA%\Programs\Kaptain\ if you followed the PATH step.

Every account on a computer has its own data folder under its own user folder. Set KAPTAIN_DATA_DIR to use another folder. To run a second, separate Kaptain next to the first, give it its own port as well, for example KAPTAIN_DATA_DIR=~/kaptain-two KAPTAIN_PORT=8820 kaptain start: with the data folder alone, kaptain start finds the first Kaptain on 8810 and says already running. kaptain serve --data DIR sets the data folder for one run.

In the data folder What it holds
kaptain.json Settings and this machine's credentials. Private to your user.
sessions.db Chats and runs
models.db Models, cloud API keys, per-model settings and agent overrides
kapsules/<name>/ Each kapsule's definition: kapsule.json, its memory and its lessons. Its workspace is .kaptain/kapsules/<name>/ in the project folder.
skills/ Your machine-wide skills
mcp_servers.json MCP servers you connected
plugins/ Tool programs dropped in to register automatically
kaptain.log, kaptain.pid The background server's log and process id, written by kaptain start
access.jsonl The access log
access-code.txt The access code, readable only by you. Written by setup (in the browser or kaptain setup), by every new access code, and by kaptain device register on a computer that had none. Delete it once your devices are paired
models/embed/, runtimes/llama.cpp/ The code-search model and the llama.cpp runtime, downloaded when you choose Kaptain's built-in code search or press Install llama.cpp for me
results/ Tool results too large for the model's window, saved whole and read back by id (Big tool results)
runtimes/ollama/ Ollama's official installer, kept after Install Ollama for me (Linux)
run/sudo-shim/ The helper that sends a sudo inside a command to Kaptain's pop-up (Approval modes). Not on Windows.
cluster-peers.json, cluster-grants.json Machines you borrow from, and the connection codes you issued
backups/ Copies of kaptain.json saved before each settings migration

Outside the data folder#

Where What
your project folder .kodegraph/ (the code index), and a .planning/ folder if Kaptain 0.0.8 or earlier made one; 0.0.9 no longer does
~/.local/share/kaptain/models/ GGUF models you download, on every operating system, unless KAPTAIN_MODELS_DIR is set. On Windows that is C:\Users\<your name>\.local\share\kaptain\models\, next to the data folder rather than in it
~/.cache/kaptain/ (~/Library/Caches/kaptain/ on macOS) Attachments and the unpacked helper Kaptain uses for Claude, in attachments/ and sidecar/. On Windows these two folders are inside the data folder, %LOCALAPPDATA%\Kaptain\, because Windows has no separate cache folder
~/llama/llama.cpp/, ~/.local/bin/llama-server A llama.cpp Kaptain built from source, when no official build fits this machine or you chose Build llama.cpp for this GPU
~/.claude.json, ~/.codex/config.toml, ~/.gemini/settings.json Only if you register Kaptain's tools with those CLIs (MCP)
next to the binary kaptain.bak, the previous version kept by kaptain update

Back up or move a machine#

  1. Stop Kaptain with kaptain stop. Never copy the databases while it runs.
  2. Copy the data folder. Copy ~/.local/share/kaptain/models/ too if you downloaded GGUF models.
  3. On the new machine, install Kaptain, put the folder in place and run kaptain start.

A registered machine's certificate moves with the folder. A trial that was never registered stays tied to the original machine.

Environment variables#

Variable What it does Default
KAPTAIN_DATA_DIR The data folder per operating system, above
KAPTAIN_PORT The port Kaptain serves on 8810
KAPTAIN_ADDR A full host:port to bind, overriding the network mode. A non-local address needs setup finished first. unset
KAPTAIN_MODEL_URL Where Ollama listens ollama_url, else http://127.0.0.1:11434
KAPTAIN_MODEL The fallback chat model for agents and the terminal the model chosen in setup
KAPTAIN_DELEGATE_MODEL The delegation worker; overrides Settings › Model Handling › Delegation at start unset
KAPTAIN_MODELS_DIR Where GGUF downloads go, and an extra place to look for them ~/.local/share/kaptain/models
KAPTAIN_LLAMA_SERVER_BIN The llama-server to use discovered
KAPTAIN_GPU_LAYERS GPU layers for llama.cpp: 0 for CPU only, 999 for all detected
KAPTAIN_EMBED_PREPROVISION 0 stops every background code-search download downloads once code search is chosen
KAPTAIN_KG_REINDEX_SECONDS How often the code index refreshes; 0 or less turns that off 120
KAPTAIN_VISION_MODEL The vision model when Settings has none unset
KAPTAIN_VISION_TIMEOUT_S How long one image description may take 600
KAPTAIN_CLI_TOOL_TIMEOUT_S How long Claude and Codex wait for a Kaptain tool 900
KAPTAIN_APPROVAL_TIMEOUT_S For Claude and Codex turns only: how long the bridge waits for your approval. Keep it equal to approval_timeout_seconds in kaptain.json, which sets the actual wait. 300
KAPTAIN_STALL_TIMEOUT Cancels a turn that has been silent this long 12m
KAPTAIN_SKILL_IMPORT_ROOTS Extra folders of skills to load none
KAPTAIN_CLOUD_URL, KAPTAIN_CLOUD_KEY, KAPTAIN_CLOUD_MODELS Adds a cloud endpoint and model ids without the UI unset
KAPTAIN_NO_ENGINE Any value starts Kaptain without its tools unset
KAPTAIN_TOOL_HARD_TIMEOUT_S The longest one tool call may run before it is cut off and the model is told why. Tools keep their own, shorter limits. 7200 (2 hours)
KAPTAIN_STOP_FORCE_GRACE_S After Stop, how long Kaptain waits for a tool to end before closing the turn anyway 30
KAPTAIN_RUN_SWEEP_INTERVAL_S How often Kaptain looks for runs left open by a turn that ended abnormally 60
KAPTAIN_RUN_SWEEP_GRACE_S How old such a run must be before the sweep closes it 180
KAPTAIN_TOOL_DIGEST_MAX_CHARS The size of the record of tool calls each reply carries into the next turn 2000

Set the same KAPTAIN_PORT or KAPTAIN_ADDR for kaptain status and kaptain stop that you used for kaptain start; they look for Kaptain where those variables point.

Update and uninstall#

Update#

Update from Settings › General › Update Kaptain (Check for updates, then Update now), or from a terminal:

Terminal
$ kaptain update --check
kaptain <version> — up to date.
$ kaptain update

kaptain update downloads the published build for your platform, checks the release manifest's signature and the file's SHA-256, runs the new binary once, then swaps it in. The old binary is kept next to it as kaptain.bak. If any step fails, your installation is left untouched. The new version runs after a restart:

Terminal
$ kaptain stop
$ kaptain start
Flag What it does
--check Reports whether an update is available; installs nothing
--force Reinstalls the published build even if the version matches
--json Machine-readable output

The update replaces the binary where it is, so its folder must be writable by you. Re-running the installer also updates.

Uninstall#

kaptain uninstall shows what it would remove and changes nothing until you add --yes:

Terminal
$ kaptain uninstall
Output

Kaptain uninstall — dry run (nothing will change)

Detected:
  data dir   /home/you/.local/share/kaptain  (176.2M)
  binary     /home/you/.local/bin/kaptain

Mode: full removal — Kaptain is stopped, then its data, cache, downloaded runtimes, binary and MCP registrations are all deleted. Nothing is left behind.

Dry run complete. Re-run with --yes to apply.

kaptain uninstall --yes stops a Kaptain started with kaptain start (stop a foreground kaptain serve first), deletes its data and cache folders, the downloaded runtimes and the binary named kaptain, removes the kaptain-engine entries it added to the Claude, Codex and Gemini CLI configs, and then checks that nothing is left (Verifying: clean.). Run it as yourself, not with sudo. Step by step:

Linux

Terminal
$ kaptain uninstall
$ kaptain uninstall --yes
$ ls -d ~/.local/share/kaptain ~/.cache/kaptain ~/.kaptain

The first command previews the list; read it. The second removes everything. The third should report "No such file" for all three.

macOS

Terminal
$ kaptain uninstall
$ kaptain uninstall --yes
$ ls -d ~/Library/Application\ Support/Kaptain ~/Library/Caches/kaptain

The last command should report "No such file" for both.

Windows

PowerShell
PS> kaptain stop
PS> kaptain uninstall
PS> kaptain uninstall --yes
PS> Test-Path $env:LOCALAPPDATA\Kaptain
PS> Test-Path $env:APPDATA\Kaptain

kaptain stop matters only if Kaptain runs from a shortcut or a startup entry. Both Test-Path lines should print False.

If kaptain is gone from your PATH but its files are still there, or your installed build has no uninstall, download the current build and run uninstall from it. A downloaded copy cleans up the installed Kaptain and never deletes itself:

Terminal
$ curl -L -o kaptain-new https://chynj.ca/download/kaptain/linux-x64
$ chmod +x kaptain-new
$ ./kaptain-new uninstall
$ ./kaptain-new uninstall --yes
$ rm kaptain-new

Use linux-arm64 on 64-bit ARM. On Windows: curl.exe -L -o kaptain-new.exe https://chynj.ca/download/kaptain/win, then .\kaptain-new.exe uninstall, .\kaptain-new.exe uninstall --yes and Remove-Item .\kaptain-new.exe.

Flag What it does
--yes Performs the removal
--identity-only Removes only this machine's licence, device identity, account sign-in and access code from kaptain.json; keeps chats and settings. An access-code.txt is left in place, but its code no longer works
--keep-access-code Saves the access code to ~/kaptain-access-code.txt first
--keep-runtimes Keeps the downloaded runtimes beside the data folder
--json Machine-readable report
--fingerprint Prints this machine's device fingerprint hash and changes nothing

It does not remove Ollama or its models, GGUF models in ~/.local/share/kaptain/models on macOS and Windows, a llama.cpp Kaptain built from source in ~/llama, your project's .kodegraph/ and .kaptain/ folders (or a .planning/ folder an earlier version made), or the PATH line you added. A Kaptain build inside a source tree, or the copy you are running, is listed under LEFT ALONE with its full path instead of deleted: running it creates the data folder again, so delete it yourself for a bare machine.

Uninstalling removes Kaptain from this machine only. It does not cancel your subscription, change your licence or reset the trial; manage those at chynj.ca/account. A full uninstall deletes this machine's access code, so the next setup makes a new one. --keep-access-code saves it first; put it back only after the new setup has finished, or setup never opens.

Reference

Krew tools reference#

Every built-in tool in Kaptain 0.0.9, in one shape: what it does, when a model uses it, what the approval gate does with it, its parameters and an example. The permission lines describe local and cloud models; Claude Code and Codex apply their own permission modes (mapping). Kaptain adds the session and approval mode to every call itself; they are not parameters.

For a local or cloud model, one tool result may fill at most 15% of the model's context window, and all of one message's results 30% (tool_result_window_percent and turn_results_window_percent in kaptain.json). A bigger result is saved whole, and the model gets a short notice instead (its size, shape, id and how to read it) and reads it with tool_result_recall. file_read and tool_result_recall size their own page to fit.

Tool Family What it does Permission
kodegraph_explore Code search Returns the verbatim source of the symbols that match a question, with their callers and callees, grouped by file. never asks
kodegraph_context Code search Returns only the code relevant to a task, within a token budget, ranked by keywords and, when an embedder is available, meaning. never asks
kodegraph_search Code search Finds a function, method or class by name or keyword, ranked. never asks
kodegraph_node Code search One symbol's file, line and signature, and its source when asked. never asks
kodegraph_callers Code search The symbols that call a given symbol. never asks
kodegraph_callees Code search The symbols a given symbol calls. never asks
kodegraph_impact Code search Everything that calls a symbol, directly or indirectly, level by level. never asks
kodegraph_files Code search The indexed files with their language and number of symbols. never asks
kodegraph_status Code search Index statistics and freshness, and live progress while an index pass runs. never asks
kodegraph_index Code search Builds or refreshes the index. never asks
file_read Files Reads a text file one page at a time and returns numbered lines. never inside the project
file_search Files Finds literal text or a pattern in files, using ripgrep, and returns each match with its file and line. never inside the project
file_write Files Creates, overwrites or appends to a text file, and says what changed. asks (a change)
file_edit Files Replaces exact text in a file. asks (a change)
patch_apply Files Applies a unified diff to the project. asks (a change)
cli_exec Shell Runs a shell command in the project folder: sh on Linux and macOS, Git Bash (or cmd.exe) on Windows. read-only commands never; others ask
test_run Shell Runs a test command and reports pass or fail with the end of the output. asks (a change)
git_op Shell Runs one git subcommand in the project. reads never; others ask
web_search Web Searches the web through DuckDuckGo and returns titles, addresses and snippets. never asks
web_fetch Web Fetches a page and returns its readable text. never asks
web_fetch_raw Web Fetches an address and returns the body as is, such as JSON or HTML. never asks
web_extract Web Fetches a page and returns its title, description, OpenGraph data, links and clean text. never asks
skill_list Skills Lists the available skills by name, source and description. never asks
skill_load Skills Loads one skill's full text into the conversation. never asks
remember Memory Records one short rule the kapsule learned: a guideline (what worked) or a guardrail (what to avoid). never asks
session_recall Memory Searches this conversation's earlier turns, including ones already folded into the summary, and returns the matching messages. never asks
tool_result_recall Memory Reads an earlier tool result by its id, a page of lines at a time, or only the lines that contain some text. never asks
tool_schema_resolve Workflow Returns the full definitions of tools the model was shown only by name. never asks
todo Workflow The model's progress list for multi-step work. never asks
time_now Workflow The current date and time, with the time zone used and where it came from. never asks
ask_user Workflow Asks you one to four multiple-choice questions and waits for the answers. never asks
delegate Delegation Hands one self-contained task to the worker model. never asks; writing output_file asks (a change)
delegate_batch Delegation Runs several delegate briefs in one call; each must name its output_file. asks (a change)
assemble Delegation Fills a template's {{KEY}} placeholders from files and writes the result. asks (a change)
delegate_status Delegation Reports the worker model, its size class and the limits of one brief. never asks
vision_analyze Vision Describes an image with the vision model: a web address, a project file or a data URL. never asks
agent_cards Agents Splits work into cards that workers run. never asks
kapsule_create Agents Creates a kapsule from a name, role, task, tools and model (Edit access). asks (a change)
kapsule_edit Agents Changes a kapsule's fields, or shows it when given only its name; a kapsule never edits itself. asks (a change)
agent_<name> Agents Runs another kapsule on a self-contained task, with that kapsule's own model, instructions, tools and permissions. never asks

Tools from connected MCP servers are listed under their own names, and every call to them asks in Ask mode unless a kapsule pre-approves the server. tool_schema_resolve is not a Krew tool: Kaptain adds it to a turn when some tools are only listed by name (How tools reach the model). Four more tools exist only when Kaptain is an MCP server for a CLI: kaptain_models, kaptain_chat, agent_list and invoke_agent (MCP).

When tools are on, a local or cloud model gets a few tools in full and looks the rest up with tool_schema_resolve (How tools reach the model). Claude Code and Codex get their tools from kaptain mcp instead.

kodegraph_explore

Returns the verbatim source of the symbols that match a question, with their callers and callees, grouped by file. The main way models explore code.

Parameter Type Required Meaning
query string yes A question or symbol names
limit integer no Most symbols to start from; default 6, at most 12
Example call
{"query": "greet"}

Returns files, each with sections: the code, its kind, line and relation (match, caller or callee).

kodegraph_context

Returns only the code relevant to a task, within a token budget, ranked by keywords and, when an embedder is available, meaning.

Parameter Type Required Meaning
query string yes The task or topic
budget_tokens integer no Token budget, up to 8000; default 2000
Example call
{"query": "how is the greeting built", "budget_tokens": 300}

Returns chunks of code with their files, or a note to try kodegraph_search when nothing matched.

Finds a function, method or class by name or keyword, ranked.

Parameter Type Required Meaning
query string yes A symbol name or keyword
kind string no function, method or class
limit integer no Most results; default 20
Example call
{"query": "greet"}
Output
{"count":1,"ok":true,"query":"greet","results":[{"file":"main.go","kind":"function","line":5,"name":"greet","parent":""}]}

kodegraph_node

One symbol's file, line and signature, and its source when asked.

Parameter Type Required Meaning
symbol string yes The symbol's name
code boolean no Include the source; default false
Example call
{"symbol": "greet", "code": true}

Returns matches, each with file, line, kind and, when asked, code.

kodegraph_callers

The symbols that call a given symbol.

Parameter Type Required Meaning
symbol string yes The symbol's name
limit integer no Most results; default 20
Example call
{"symbol": "greet"}

Returns callers, each with its name, qualified name, kind, file, line, the line of the call (at_line), the relation, and how sure the match is (resolution, confidence), plus count, exact and possible.

kodegraph_callees

The symbols a given symbol calls.

Parameter Type Required Meaning
symbol string yes The symbol's name
limit integer no Most results; default 20
Example call
{"symbol": "main"}

Returns callees, each with name, file and line.

kodegraph_impact

Everything that calls a symbol, directly or indirectly, level by level.

Parameter Type Required Meaning
symbol string yes The symbol's name
depth integer no Levels to follow; default 3, at most 6
offset integer no Skip this many, to page on with next_offset
Example call
{"symbol": "greet"}

Returns levels, each symbol written as name (file:line), with impacted, impacted_nodes, exact and possible, and next_offset when one answer cannot hold them all.

kodegraph_files

The indexed files with their language and number of symbols.

Parameter Type Required Meaning
limit integer no Most files; default 50
Example call
{}
Output
{"count":1,"files":[{"lang":"go","path":"main.go","symbols":2}],"ok":true}

kodegraph_status

Index statistics and freshness, and live progress while an index pass runs.

No parameters.

Example call
{}

Returns index_status (ready, building or not_built), root, index_state, stale, files, symbols, call_edges, vectors and store, and progress while a pass runs. Which embedder is in use is not part of it: see Settings › Model Handling › KodeGraph Embedder. Every KodeGraph answer also carries index_state.

kodegraph_index

Builds or refreshes the index. Unchanged files are skipped, and the pass runs in the background unless asked to wait.

Parameter Type Required Meaning
confirm boolean no Index a home folder or a very large tree on purpose
wait boolean no Wait for the pass to finish; default false
scan string no auto (a quick check first) or hash (read every file)
Example call
{"wait": true}
Output
{"call_edges":1,"changed_files":1,"deleted_files":0,"files":1,"indexed_at":"2026-10-15T11:48:38-07:00","ok":true,"root":"/home/you/project","store":"sqlite+fts5","symbols":2,"vector_warm":"not_needed","vectors":{"done":0,"total":2}}

File tools#

file_read

Reads a text file one page at a time and returns numbered lines. Without a limit, a page is sized to the model's context window: about 380 lines at a 32K window and about 1,560 at 128K, never fewer than 120. Through kaptain mcp that is a 128K window unless mcp_result_window_tokens says otherwise, and where no window is known a page is 250 lines. A local or cloud model is told its page size. One call returns at most 2,000 lines or 48,000 characters, and a line longer than 2,000 characters is cut with a note. A page that is not the whole file says so and gives the offset to continue from. Binary files are refused; an image is pointed at vision_analyze.

Parameter Type Required Meaning
path string yes Relative to the project, or absolute
offset integer no First line, from 1; default 1
limit integer no Lines to return, at most 2000; without it, the page size above

start_line and end_line still work in place of offset and limit.

Example call
{"path": "main.go", "offset": 1, "limit": 5}
Output
{"content":"1\tpackage main\n2\t\n3\timport \"fmt\"\n4\t\n5\tfunc greet(name string) string { return \"hello \" + name }","file_bytes":131,"hint":"showing lines 1–5 of 7 (you asked for 5 lines) — NOT the whole file: use offset=6 to continue","next_offset":6,"ok":true,"path":"main.go","shown_lines":[1,5],"total_lines":7,"truncated_by":"limit"}

Finds literal text or a pattern in files, using ripgrep (or a built-in search when ripgrep is not installed), and returns each match with its file and line.

Parameter Type Required Meaning
query string yes Text or a regular expression
path string no A folder to search; default the project
glob string no A file-name pattern such as *.go
is_regex boolean no Treat the query as a regular expression
context_lines integer no Lines around each match, up to 20
Example call
{"query": "greet", "context_lines": 1}

Returns count and matches as path:line: text. A search stops at 20,000 matches (file_search_max_matches); a long list is saved and read by id.

file_write

Creates, overwrites or appends to a text file, and returns the diff.

Parameter Type Required Meaning
path string yes Relative to the project
content string yes The full content, or the text to append
mode string no overwrite (default), append or create
Example call
{"path": "notes.md", "content": "# Notes\n"}

The model gets a line saying what changed and the diff, cut at 20 lines with an id that fetches the rest through tool_result_recall; the full diff stays on the card. Writing exactly what the file already holds says nothing was written.

file_edit

Replaces exact text in a file. The text must match exactly and be unique unless replace_all is set. edits makes several replacements in one call, all or nothing, under one approval. A model may name the file inside each edit instead of once at the top; edits naming two different files are refused, one file per call. If the file changed on disk since the model read it, an edit whose text still matches exactly is applied to the current file and the result says the file had changed; a loose or missing match is refused with a request to re-read.

Parameter Type Required Meaning
path string yes Relative to the project
old_string string see below The exact text to replace
new_string string see below The replacement
replace_all boolean no Replace every occurrence
edits array see below [{old_string, new_string, replace_all}] for several edits; each may also carry path
Example call
{"path": "main.go", "old_string": "hello ", "new_string": "hi "}

The model gets one line saying what changed, such as "Applied to main.go: lines 2–8, +1 −1" (the changed lines with 3 lines of context around them), and the diff, cut at 20 lines with an id that fetches the rest through tool_result_recall. An edit that changes nothing says the file is unchanged. Give either old_string with new_string, or edits.

patch_apply

Applies a unified diff to the project.

Parameter Type Required Meaning
patch string yes The unified diff
Example call
{"patch": "--- a/main.go\n+++ b/main.go\n@@ …"}

Returns ok, applied, the diff and the tool output.

Shell tools#

cli_exec

Runs a shell command in the project folder: sh on Linux and macOS, Git Bash (or cmd.exe) on Windows. See also Long commands and background jobs.

For a local or cloud model in Kaptain, a command still running at its time limit is not stopped: it continues in the background as a job, the model gets the output so far and a job_id, and a strip above the chat box shows it with a Stop button. background: true starts a server or watcher that way from the start. A job ends when it finishes, when you or the model stop it, when its chat is deleted or when Kaptain stops; a command that outran its limit is also stopped after shell_job_max_minutes in kaptain.json (default 60). Through kaptain mcp, a command is stopped at its limit.

Parameter Type Required Meaning
command string yes, unless job_id The command
timeout integer no Seconds; default 30, at most 300
working_dir string no A folder inside the project; for a kapsule, its workspace by default or a folder it may change (Edit access)
background boolean no Start the command as a background job and return at once
job_id string no Act on a background job: without wait or signal, return its new output
wait integer no With job_id: seconds to wait for it to finish, at most 300
signal string no With job_id: TERM stops it
Example call
{"command": "ls -la"}
Output
{"auto_run_reason":"read-only allowlist","command":"ls -la","exit_code":0,"gated":false,"ok":true,"read_only":true,"risk":"safe","stderr":"","stdout":"total 16\n…"}

A command that became a job returns job_id, state ("running"), running_for and the output so far. Reading a job returns its state, new output and, once it ended, exit_code and the reason.

test_run

Runs a test command and reports pass or fail with the end of the output.

Parameter Type Required Meaning
command string yes The test command, such as go test ./...
timeout integer no Seconds; default 300, at most 1800
Example call
{"command": "go test ./..."}

Returns ok, passed, exit_code and the output.

git_op

Runs one git subcommand in the project.

Parameter Type Required Meaning
op string yes The subcommand, such as status
args string no Further arguments
Example call
{"op": "status"}

Returns ok, exit_code and the output.

Web tools#

Searches the web through DuckDuckGo and returns titles, addresses and snippets.

Parameter Type Required Meaning
query string yes The search
max_results integer no Default 5, at most 20
Example call
{"query": "go 1.25 release notes"}

Returns engine, count and results, each with title, url and snippet.

web_fetch

Fetches a page and returns its readable text. Page text is marked as untrusted content. A page body is read up to 8 MB (web_fetch_max_mb), and a long text is saved and read by id.

Parameter Type Required Meaning
url string yes An http or https address
Example call
{"url": "https://go.dev/doc/"}

Returns status, title and text.

web_fetch_raw

Fetches an address and returns the body as is, such as JSON or HTML. The body is marked as untrusted content; a long body is saved and read by id.

Parameter Type Required Meaning
url string yes An http or https address
Example call
{"url": "https://api.github.com/repos/golang/go"}

Returns status and body.

web_extract

Fetches a page and returns its title, description, OpenGraph data, links and clean text.

Parameter Type Required Meaning
url string yes An http or https address
max_chars integer no Cut the text at this many characters; by default the whole text
Example call
{"url": "https://example.com"}

Returns title, description, opengraph, links and text.

Skill tools#

skill_list

Lists the available skills by name, source and description.

Parameter Type Required Meaning
filter string no A keyword
Example call
{}
Output
{"count":1,"skills":[{"description":"Draft release notes from a git log range.","name":"release-notes","source":"global"}]}

skill_load

Loads one skill's full text into the conversation.

Parameter Type Required Meaning
name string yes The skill's name
Example call
{"name": "release-notes"}

Returns name, source and content, or the available names when not found.

Memory tools#

remember

Records one short rule the kapsule learned: a guideline (what worked) or a guardrail (what to avoid). It is kept only if the run finishes cleanly, then given to later runs. Up to 64 lessons of 240 characters each.

Parameter Type Required Meaning
text string yes The rule in one sentence, at most 240 characters
kind string no guideline (default) or guardrail
Example call
{"text": "Always call time_now before dating a digest"}

Returns ok and a note that the lesson is pending until the run finishes cleanly.

session_recall

Searches this conversation's earlier turns, including ones already folded into the summary, and returns the matching messages. Each message is cut at 2,000 characters. It works in Kaptain's own chats; through kaptain mcp it has no conversation to search and says so.

Parameter Type Required Meaning
query string yes What to look for
limit integer no Most messages; default 6
Example call
{"query": "deploy target"}

Returns found, count and messages.

tool_result_recall

Fetches an earlier tool result by its id, from this turn or an earlier one: a page of lines, one item of a list, or only the lines that contain some text. Every result carries its id in square brackets, such as [12345678-r03-c01], and the model sees it on the result and in the record each reply keeps of its tool calls. A result too big for the model is saved whole, and this tool reads it: a JSON result one field per line, a list result by item. Through kaptain mcp it reads the results that were too big to send.

Parameter Type Required Meaning
id string yes The result's id
offset integer no First line, from 1; default 1
limit integer no Lines; default 200, at most 1000
search string no Return only the lines that contain this text, up to 60 (query also works)
item integer no For a list result: the item to return, from 1
char_offset integer no Continue inside a long line or item
Example call
{"id": "12345678-r03-c01", "offset": 201}

Returns found, tool, total_lines, shown_lines and the numbered content, at most 24,000 characters per call, with next_offset while lines are left.

Workflow tools#

todo

The model's progress list for multi-step work. Finished items drop out of the prompt.

Parameter Type Required Meaning
todos array no [{id, title, status}]; status is pending, in_progress, completed or cancelled. Omit to read the list.
merge boolean no Update only the listed ids instead of replacing the list
Example call
{"todos": [{"id": "1", "title": "read main.go", "status": "in_progress"}]}

Returns the action, the todos and counts by status.

time_now

The current date and time, with the time zone used and where it came from.

Parameter Type Required Meaning
timezone string no An IANA zone; default the kapsule's zone, else this machine's
Example call
{"timezone": "America/Toronto"}
Output
{"date":"2026-10-15","iso":"2026-10-15T14:51:35-04:00","ok":true,"time":"14:51:35","timezone":"America/Toronto","timezone_abbrev":"EDT","timezone_source":"requested","utc":"2026-10-15T18:51:35Z","weekday":"Thursday",…}

ask_user

Asks you one to four multiple-choice questions and waits for the answers.

Parameter Type Required Meaning
questions array yes 1 to 4 items of {question, header, multi_select, options: [{label, description}]}, with 2 to 4 options each
Example call
{"questions": [{"header": "Target", "question": "Deploy to staging or prod?", "options": [{"label": "staging"}, {"label": "prod"}]}]}

Returns answered and the answers. Unanswered, the model is told to choose the most reasonable option itself.

tool_schema_resolve

Returns the full definitions of tools the model was shown only by name, under "Other tools available", so it can call them. Kaptain adds it for local and cloud models whenever some tools are listed by name only (how tools reach a model). It answers only for tools the model may use. A model may also call a listed tool directly: right arguments run it, wrong ones bring back its definition and what was wrong.

Parameter Type Required Meaning
names array yes Tool names from the list
Example call
{"names": ["git_op", "web_fetch"]}

Returns schemas and unknown, the names that are not tools the model can use here.

Delegation tools#

delegate

Hands one self-contained task to the worker model. Without tools, the result passes a quality check. With output_file, the result goes to that file and only stats and an excerpt come back. With tools, the worker gets its own small toolbelt; it can never delegate again or ask you.

Parameter Type Required Meaning
task string yes A complete, standalone brief; numbered steps work best
context string no Small inline context
context_files array no Project files to put in the brief
output_file string no Where to write the result
tools array no The worker's tools, such as ["file_read", "file_search"]
Example call
{"task": "1. Read README.md 2. List every command-line flag", "context_files": ["README.md"], "output_file": "notes/flags.md"}

With output_file, returns written, the quality result and an excerpt; the file is written even when the quality check fails, with a warning. Without it, returns the response and the quality result. With tools, it returns the worker's answer and, with output_file, output_written: true only if the file changed during the run, with a warning when it did not. A worker that is a Claude or Codex CLI on another machine adds runs_on, and its changes take place on that machine.

delegate_batch

Runs several delegate briefs in one call; each must name its output_file.

Parameter Type Required Meaning
items array yes [{task, output_file, context, context_files}]
Example call
{"items": [{"task": "Summarize a.go", "output_file": "out/a.md", "context_files": ["a.go"]}]}

Returns succeeded, total and items, one result per item.

assemble

Fills a template's {{KEY}} placeholders from files and writes the result. No model is called.

Parameter Type Required Meaning
template_file string yes The template
output_file string yes Where to write the result
replacements object yes Each KEY and the file that fills it
Example call
{"template_file": "tpl/report.md", "output_file": "report.md", "replacements": {"A": "out/a.md"}}

Returns ok and the file written.

delegate_status

Reports the worker model, its size class and the limits of one brief.

No parameters.

Example call
{}
Output
{"model":"qwen3.5:4b","ok":true,"profile":"qwen3.5:4b (unknown size, tier small) — granularity: one component, one page section, or one small file per call; per call ≤ ~4372 prompt tokens, output budget 3000, ctx 8192","root":"/home/you/project","surface":"krew (native)"}

The vision tool#

vision_analyze

Describes an image with the vision model: a web address, a project file or a data URL. Images larger than 2,000 pixels or 5 MB are scaled down; one that cannot be brought under 5 MB is refused.

Parameter Type Required Meaning
url string yes The image
prompt string no What to look for
max_tokens integer no Answer budget; default from Settings (1,000)
Example call
{"url": "docs/screenshot.png", "prompt": "What error is shown?"}

Returns the analysis and the model that produced it.

Agent tools#

agent_cards

Splits work into cards that workers run. Cards without parents run in parallel; a card with parents starts when they finish and receives their results. Cards are matched with the kapsule's proven workers.

Parameter Type Required Meaning
action string yes propose, add_card, ready, complete, library or library_delete
cards array for propose [{title, body, role, tools, persona, parents}]
title, body, role, persona, tools string for add_card One card; tools is a comma list, or none
card_id, success, result, evidence various for complete Which card, whether it verifiably succeeded, and the evidence
id string for library_delete The library worker to delete
limit integer no library: most rows; default 50
Example call
{"action": "library"}
Output
{"agents":[],"ok":true}

agent_<name>

Runs another kapsule on a self-contained task, with that kapsule's own model, instructions, tools and permissions. It cannot see your conversation.

Parameter Type Required Meaning
task string yes A complete, standalone task
Example call
{"task": "Find three sources on X"}

Returns the other kapsule's result.

CLI reference#

Every kaptain command in 0.0.9. Running kaptain with no command, or kaptain --help, prints the main list; kaptain <command> --help prints that command's line, or its own usage for update, nodes, channels and kodegraph; run kaptain skill with no arguments for its usage. Those five commands work but are not in the main list yet.

Command What it does
kaptain start Starts Kaptain in the background in its own session, waits up to 30 seconds for the interface, prints where it is and opens your browser.
kaptain stop Stops the running Kaptain and the model servers it started.
kaptain status Says whether Kaptain is running and where, and where its access code is saved.
kaptain access-code rotate Makes a new access code for this computer; the old one stops at once.
kaptain restart Restarts the running Kaptain onto this binary; --if-idle waits for no turn to be running.
kaptain install-state One line of JSON for installers: version, data folder, whether it is set up, the device, and what is running.
kaptain serve Runs Kaptain in the foreground, logging to the terminal, until you press Ctrl+C.
kaptain setup The setup wizard in the terminal.
kaptain version Prints the version and whether the Claude helper is built in.
kaptain sidecar check Unpacks the built-in Claude helper and checks that it runs on this machine.
kaptain update Downloads, verifies and installs the published build; restart to run it.
kaptain uninstall Shows what would be removed; --yes removes it.
kaptain migrate Brings kaptain.json up to the current settings format and prints the report.
kaptain doctor Checks the GPU, llama-server, Ollama, the CLIs, GGUF files and the shell.
kaptain models Lists every model Kaptain can reach: CLIs, cloud models, GGUF files, Ollama models.
kaptain chat A chat in the terminal with any model, in the current folder.
kaptain delegate "<task>" A simple terminal flow: one model plans two to four subtasks, runs each, then combines the results.
kaptain spawn spawn ollama starts Ollama if it is installed and not running.
kaptain usage Token totals from the Claude Code and Codex session records on this machine.
kaptain agent Lists and drives kapsule agents.
kaptain skill Lists skills, or installs them from a folder, .zip, git URL or owner/repo.
kaptain mcp Runs Kaptain's toolbelt as an MCP server named kaptain-engine over stdio.
kaptain mcp Manages the MCP servers you connect to Kaptain.
kaptain mcp Adds Kaptain's tools to your own CLI's configuration, removes them, or checks.
kaptain mcp health Self-tests of this binary's MCP server.
kaptain kodegraph The code graph from a terminal; kaptain kg for short.
kaptain remote Shows or changes remote access over your tailnet, with readiness checks.
kaptain nodes Sharing models between your Kaptains from a terminal.
kaptain device register binds this machine to your account through an approval in the account portal and keeps its access code.
kaptain license status shows the entitlement from local files.
kaptain account status shows the signed-in account and this device.
kaptain billing open Opens billing in the account portal.
kaptain channels Connects Kaptain to Telegram, Signal, Discord or Slack and manages who may talk to it.
kaptain engine Runs Kaptain's tool engine on its own, for development.

Every command runs against the data folder in KAPTAIN_DATA_DIR, or the default for your system, and the port in KAPTAIN_PORT or 8810. Use the same values for start, status and stop.

Run Kaptain#

kaptain start

Usage
kaptain start

Starts Kaptain in the background in its own session, waits up to 30 seconds for the interface, prints where it is and opens your browser. Each start begins a fresh kaptain.log. Prints kaptain already running (pid N) and the address when its pid file names a live process or anything already listens on its port.

Output
kaptain started (pid 3150395)
  UI:    http://127.0.0.1:8810
  bind:  127.0.0.1:8810
  logs:  /home/you/.local/share/kaptain/kaptain.log
  stop:  kaptain stop

Details and output: Start Kaptain.

kaptain stop

Usage
kaptain stop

Stops the running Kaptain and the model servers it started. It finds Kaptain by its pid file. Without one, it stops whatever program is listening on Kaptain's port, even one that is not Kaptain, so do not run another program on 8810.

Output
kaptain stopped (pid 3150395)

kaptain status

Usage
kaptain status

Says whether Kaptain is running and where.

Output
kaptain: running (pid 3150395) → http://127.0.0.1:8810
access code: saved in /home/you/.local/share/kaptain/access-code.txt

The second line says where the access code is: access-code.txt while that file exists, then the api_token in …/kaptain.json, or none yet — run kaptain setup before setup. When Kaptain refuses the code (see below), it says access code: REFUSED — and the reason.

kaptain access-code rotate

Usage
kaptain access-code rotate

Makes a new access code for this computer, prints it once, saves it to kaptain.json and access-code.txt, and ends every browser session. A running Kaptain uses it from its next request; no restart. It is also the way back when Kaptain refuses a code it did not make. Output and details: Get a new access code.

kaptain restart

Usage
kaptain restart [--if-idle] [--wait SECONDS]

Restarts the running Kaptain onto this binary, for example after kaptain update. The installer runs it with --if-idle after an update.

Flag Meaning
--if-idle Only when no turn is running. A busy Kaptain is left as it is, with exit code 3 and the line below.
--wait SECONDS Wait that long for the restarted Kaptain to answer, then print where it runs
Output
Kaptain (pid 4121449, <version>) is restarting onto <version>.

When a turn is running and you gave --if-idle, it says "Kaptain is busy (1 turn(s) running) — the new version starts at its next restart: kaptain restart." When nothing runs: "Kaptain is not running — start it with kaptain start."

kaptain install-state

Usage
kaptain install-state --json

What an installer needs to know about this machine, as one line of JSON. Reads only.

Output
{"version":"<version>","data_dir":"/home/you/.local/share/kaptain","config":"present","set_up":true,"set_up_at":"2026-10-28","device":"none","running":{"pid":4121449,"url":"http://127.0.0.1:8810","version":"<version>"}}

kaptain serve

Usage
kaptain serve [--root DIR] [--data DIR]

Runs Kaptain in the foreground, logging to the terminal, until you press Ctrl+C. Use it under a service manager or to watch the log. Writes no pid file.

Flag Meaning
--root DIR The project folder for this run, when none is set in Settings
--data DIR The data folder for this run, like KAPTAIN_DATA_DIR

kaptain setup

Usage
kaptain setup [--force]

The setup wizard in the terminal. Stop Kaptain first. Creating an account here first asks you to agree to the Terms of Service and Privacy Policy ([y/N]); without a yes, no account is created and setup stops. On a machine that is already set up it changes nothing and says so.

Flag Meaning
--force Goes through the wizard again on a machine that is already set up, starting from the choices on record. The access code, device and licence stay.

Details and output: Set up from the terminal.

kaptain version

Usage
kaptain version [--json]

Prints the version and whether the Claude helper is built in. --json adds whether this binary carries CHYNJ's signing keys, with their fingerprints, and the helper's size. kaptain --version and -v work too.

Flag Meaning
--json Machine-readable output
Output
kaptain <version>
claude sidecar: embedded (linux-amd64, <size> MB)

kaptain sidecar check

Usage
kaptain sidecar check [--json] [--timeout 90s]

Kaptain runs Claude through a small helper built into the binary, unpacked to your cache folder the first time a Claude turn runs. This command unpacks it the same way and runs its offline self-check, so you can tell before a chat whether Claude turns can start on this machine. Exit code 0 means it ran and answered; 1 names the stage that failed, in the system's own words.

Flag Meaning
--json The result as one JSON object
--timeout How long the helper may take to start and answer; default 90s
Output
claude sidecar check — linux-amd64
  embedded    yes (<bytes> bytes)
  extracted   <cache folder>/… (<mode>)
  answered    <platform>/<arch>, <runtime> (<ms> ms)
OK — the embedded Claude sidecar runs on this machine.

A build without the helper fails at the first stage:

Output
claude sidecar check — linux-amd64
  embedded    no
kaptain sidecar check FAILED at embed: this build carries no embedded Claude sidecar for linux-amd64 — a plain `go build` has none; build.sh and the candidate build embed it

kaptain update

Usage
kaptain update [--check] [--force] [--json]

Downloads, verifies and installs the published build; restart to run it.

Flag Meaning
--check Report only; install nothing
--force Reinstall even if the version matches
--json Machine-readable output

Details and output: Update.

kaptain uninstall

Usage
kaptain uninstall [--yes]

Shows what would be removed; --yes removes it.

Flag Meaning
--yes Perform the removal
--identity-only Remove only licence and device identity
--keep-access-code Save the access code to ~/kaptain-access-code.txt first
--keep-runtimes Keep downloaded runtimes
--fingerprint Print this machine's fingerprint hash and change nothing
--json Machine-readable report

Details and output: Uninstall.

kaptain migrate

Usage
kaptain migrate

Brings kaptain.json up to the current settings format and prints the report. Most commands do this by themselves before running (not version, help, install-state or sidecar check); while Kaptain is running they leave it for Kaptain's next start. A backup goes to backups/ first.

Output
{"changed":false,"from_schema":1,"to_schema":1,"app_version":"<version>"}

kaptain doctor

Usage
kaptain doctor [--json]

Checks the GPU, llama-server, Ollama, the CLIs, GGUF files and the shell. Reads only.

Flag Meaning
--json Machine-readable output

Details and output: See your models from the terminal.

Models and chat#

kaptain models

Usage
kaptain models

Lists every model Kaptain can reach: CLIs, cloud models, GGUF files, Ollama models.

Details and output: See your models from the terminal.

kaptain chat

Usage
kaptain chat [model] [--tools]

A chat in the terminal with any model, in the current folder. Without a model it uses KAPTAIN_MODEL, the model chosen in Kaptain, the delegation worker, then a model that can chat on this machine (GGUF or Ollama), then an installed CLI or a cloud model that can chat. Type your message at the › prompt; Ctrl+D quits.

Flag Meaning
--tools Gives the model Krew tools. In the terminal they run without asking, like a trusted command-line tool, so use it only in a folder you trust.
Output
Kaptain's log: /home/you/.local/share/kaptain/kaptain.log
loading model… ready
kaptain chat — qwen3:8b · tools   (Ctrl-D to quit)

›

kaptain delegate "<task>"

Usage
kaptain delegate "<task>"

A simple terminal flow: one model plans two to four subtasks, runs each, then combines the results. It uses KAPTAIN_MODEL, the model chosen in Kaptain, the delegation worker, or an Ollama model on this machine that can chat, in that order, through Ollama (or the address in KAPTAIN_MODEL_URL); a model on another runtime is passed over. With none it stops with no chat-capable model for kaptain delegate: … — pick a model in Settings.

kaptain spawn

Usage
kaptain spawn ollama | <model.gguf> [port]

spawn ollama starts Ollama if it is installed and not running. spawn <model.gguf> starts a llama-server for that file, on port 8080 unless you give one.

Output
ollama is serving

kaptain usage

Usage
kaptain usage [--json | --watch]

Token totals from the Claude Code and Codex session records on this machine.

Flag Meaning
--json Every session as JSON
--watch Stream updates

Details and output: Token usage from the terminal.

Agents and skills#

kaptain agent

Usage
kaptain agent <list | run | chat | history | enable | disable | set-model>

Lists and drives kapsule agents.

Details and output: Kapsules from the terminal.

kaptain skill

Usage
kaptain skill <list | add>

Lists skills, or installs them from a folder, .zip, git URL or owner/repo. kaptain skills works too.

Flag Meaning
list --harness <cli> Also show that CLI's own skills; <cli> is claude or codex
add … --replace Overwrite a skill with the same name

Details and output: Add a skill.

Tools and MCP#

kaptain mcp

Usage
kaptain mcp

Runs Kaptain's toolbelt as an MCP server named kaptain-engine over stdio. This is what CLIs start; you rarely run it yourself.

Details and output: Kaptain as an MCP server.

kaptain mcp

Usage
kaptain mcp <add | add-json | list | enable | disable | remove>

Manages the MCP servers you connect to Kaptain.

Details and output: Connect a server.

kaptain mcp

Usage
kaptain mcp <register | unregister | install-status> <claude | codex | gemini>

Adds Kaptain's tools to your own CLI's configuration, removes them, or checks. Prints JSON.

Details and output: Kaptain as an MCP server.

kaptain mcp health

Usage
kaptain mcp health · kaptain mcp smoke [--delegate]

Self-tests of this binary's MCP server. health exits non-zero when unhealthy.

Flag Meaning
--delegate Also test the delegation path

Details and output: Kaptain as an MCP server.

kaptain kodegraph

Usage
kaptain kodegraph <index | status | search | explore | node | callers | callees | impact | context | ensure-embedder>

The code graph from a terminal; kaptain kg for short. Prints JSON. It works on the project folder chosen in Settings, or the folder you give with --root, and names the folder and where it came from on its first line. index waits for the pass and its vectors.

Flag Meaning
--root DIR The folder to index or query; default the project folder from Settings
--no-vectors index: do not wait for the vectors
--confirm index: index a home folder or a very large tree on purpose
--kind K search: function, method or class
--budget N context: token budget; default 2000

Details and output: God's Eye and KodeGraph.

Network, devices and licence#

kaptain remote

Usage
kaptain remote [on | off] [--json]

Shows or changes remote access over your tailnet, with readiness checks.

Details and output: kaptain remote.

kaptain nodes

Usage
kaptain nodes <status | verify | token | models | ask> [--json]

Sharing models between your Kaptains from a terminal.

Details and output: Pairing from the terminal.

kaptain device

Usage
kaptain device <register | status>

register binds this machine to your account through an approval in the account portal and, on a computer that has an access code, keeps it (a computer with none gets one, printed once); on a registered computer it shows the registration and asks before starting again. status shows the local certificate and entitlement. kaptain device with nothing after it prints the usage and the registration statement, ending "A licence key alone never registers a computer. Signing in is always required."

Flag Meaning
--nickname NAME register: the name shown in the portal; default the hostname
--no-browser register: do not open a browser
--json Machine-readable output
--again register: register a computer that is already registered, without asking

Details and output: Register a machine.

kaptain license

Usage
kaptain license <status | refresh> [--json]

status shows the entitlement from local files. refresh asks the licence server for a new one and says why if it cannot.

Flag Meaning
--json Machine-readable output

Details and output: Check where a machine stands.

kaptain account

Usage
kaptain account <status | open> [--json]

status shows the signed-in account and this device. open opens the account portal.

Flag Meaning
--json Machine-readable output

Details and output: Check where a machine stands.

kaptain billing open

Usage
kaptain billing open

Opens billing in the account portal. Payment details stay with the payment provider.

kaptain channels

Usage
kaptain channels <list | setup | pending | approved | approve | revoke | groups | allow-group | deny-group>

Connects Kaptain to Telegram, Signal, Discord or Slack and manages who may talk to it.

Flag Meaning
--account ID Which connection, when you have more than one

Details and output: Channels.

Advanced#

kaptain engine

Usage
kaptain engine <start | status | version>

Runs Kaptain's tool engine on its own, for development. kaptain serve already runs it inside the same process, so you do not need this to use Kaptain.

Troubleshooting#

Find the message or symptom, then the fix. When in doubt, kaptain status, kaptain doctor and the log (kaptain.log in the data folder) say most of what is wrong.

Installing and starting#

Symptom Cause Fix
command not found: kaptain ~/.local/bin is not on your PATH Do the PATH step, or run ~/.local/bin/kaptain start. type -a kaptain shows every copy.
macOS: "cannot be opened because the developer cannot be verified" The binary was downloaded in a browser and is not yet notarized xattr -d com.apple.quarantine <file>, or System Settings › Privacy & Security › Open Anyway (macOS)
Windows: "Windows protected your PC" The build is not yet signed More info, then Run anyway
kaptain start says kaptain already running (pid N), but nothing works Another program is using port 8810; kaptain start reports whatever listens there Stop that program, or run Kaptain elsewhere: KAPTAIN_PORT=8820 kaptain start, and use the same variable for status and stop
kaptain: serve: listen tcp 127.0.0.1:8810: bind: address already in use The same, from kaptain serve: another program holds the port As above
No GPU: kaptain doctor says GPU: cpu (CPU), and the llama.cpp install says "It runs on the CPU (no GPU detected)." This machine has no GPU Kaptain can use Nothing is broken: local models run on the CPU, more slowly. Pick a smaller model (the wizard marks which fit), or use a CLI or cloud model. If a GPU is present but unusable, Fix GPU access appears under Settings › Network Access › Connection.
kaptain: the access code (api_token) in …/kaptain.json is too short … (or is empty, or has characters a code Kaptain makes never has) — Kaptain will not serve with it api_token was edited by hand after setup; Kaptain serves only with a code it made kaptain access-code rotate, then kaptain start (Get a new access code)
process started … but it is not serving The server stopped while starting Read kaptain.log. A line refusing to bind non-loopback address … complete setup on localhost first means a network mode or KAPTAIN_ADDR was set before setup finished: finish setup on this machine first.
The browser did not open No browser opener on this machine, such as a server Open the UI: address kaptain start printed
kaptain status says stopped while Kaptain runs It started with a different KAPTAIN_PORT or KAPTAIN_ADDR Use the same variables for status and stop
Windows: kaptain stop cannot find Kaptain Windows has no port lookup, so stop uses the pid file Stop it from the Task Manager, then use kaptain start and kaptain stop from then on
kaptain update fails: cannot write the directory The binary is in a folder you do not own, such as /usr/local/bin Reinstall with the installer into ~/.local/bin
kaptain uninstall ends with left … The binary is in a folder only sudo can change Delete that file with sudo rm, as you installed it

Setup and access#

Symptom Cause Fix
Finish setup fails: verify your email A trial needs a verified email Open the verification email, then press Finish setup again
Finish setup fails: trial already used This machine already had its trial Subscribe at chynj.ca/account and sign in on this machine again; a licence key alone does not register it
Finish setup fails: device limit reached Your licence has all its devices Free a seat at chynj.ca/account: Sign out or Remove an old device under Devices using your license
Create account stays off with "Can't confirm the current Terms right now; try again shortly." Kaptain could not read the current Terms from CHYNJ, so it cannot ask you to agree to them Check the internet connection and press Try again, or create the account at chynj.ca/account and sign in
"The Terms of Service were updated … so no account was created yet." The Terms changed while the form was open, or this build is too old to send the current version Review the Terms shown, tick the box again and retry; if it keeps happening, kaptain update or create the account at chynj.ca/account and sign in
"CHYNJ cannot offer accounts, trials or licences where you are connecting from, because Canadian sanctions law does not allow it." You are connecting from a place CHYNJ cannot serve See chynj.ca/legal/availability
A banner "Kaptain is running — this computer's licence needs attention", and views say "Waiting on this computer's licence" Requests answer 402 Payment Required with entitlement_required: "Kaptain needs a current signed device entitlement. Open Account & License to reconnect, subscribe, or restore this device." Press Open Account & Licence in the banner; the reason and the fix are in When Kaptain answers 402
{"error":"unauthorized","action":"pair","hint":"enter this device's Kaptain access code"} (401) The request carried no access code and no paired session, or an old one In a browser, pair with the access code. A script sends Authorization: Bearer chynj_…
"A licence key alone never registers this computer — sign in to your CHYNJ account" (key_needs_signin) A licence key was typed on a computer with no CHYNJ account signed in Press Sign in to your CHYNJ account; the key is kept and used once you have signed in. In a terminal, answer y to Sign in now and keep this key?, or run kaptain device register
Pair this browser with Kaptain appears This browser has no session yet, or the access code changed Enter the access code
access_code_refused (401), or the pairing screen says "This computer's access code is not one Kaptain made" The code in kaptain.json was edited by hand and Kaptain refuses it On the computer where Kaptain runs: kaptain access-code rotate (Get a new access code)
"That code didn't match — check and try again." A typo, or an old code Copy the code again. kaptain status prints where it is saved. To replace it: Get a new access code
Setup is locked after onboarding Setup was finished, so its pages need the access code Open /?force_setup=1 in a browser already paired with this Kaptain
Client is not allowed to reach Kaptain. (403) The address you came from is not one Kaptain admits in its current mode, such as a device outside your tailnet Open Kaptain from this machine, or from a device on your tailnet in Tailscale mode. To go back to local only: kaptain remote off, then restart.
Kaptain in Tailscale mode does not open at 127.0.0.1 It listens on the tailnet address only Open http://100.x.y.z:8810
Other devices cannot reach Kaptain after a restart in Tailscale mode Tailscale was down when Kaptain started, so it listens on this machine only Start Tailscale, then restart Kaptain
This device is not on the allowed-devices list for this Kaptain instance. (403) The device lock is on and this device is not allowed, or Kaptain cannot reach Tailscale to check Allow the device under Settings › Network Access from this machine or an allowed device, and make sure Tailscale is running
Host header is not allowed. (421) You used a machine name or HTTPS name Kaptain does not know Add it to allowed_hosts (HTTPS over Tailscale), or use the 100.x.y.z address
A phone cannot load Kaptain at all Kaptain is in Localhost only mode, or the phone is not on your tailnet Switch to Tailscale and restart; check tailscale status lists the phone
A burst of unauth requests in the access log A browser tab that was never paired is polling Pair it, or close it

Models#

Symptom Cause Fix
ollama: NOT reachable in kaptain doctor Ollama is not installed or not running Install Ollama, or run ollama serve
llama-server binary not found No llama-server for GGUF models Install llama.cpp for me in the setup wizard or Install llama.cpp now under Settings › Model Handling › KodeGraph Embedder (GGUF), or set the path of your own in Settings › Runtimes › llama.cpp Runtime
llama-server needs system libraries this machine does not have: libgomp.so.1 A minimal Linux install lacks a library the downloaded llama.cpp needs Press Install libgomp1 for me (or the package named), or run the command shown, then Retry
The llama.cpp install says DEGRADED: this build runs on the CPU only No GPU build of llama.cpp ran on this machine; llama.cpp publishes no CUDA build for Linux In Settings › Runtimes › llama.cpp Runtime, press the Install … build it offers or Build llama.cpp for this GPU, or set the path of a GPU build of llama-server there
not a valid GGUF … begins with "<!do" A web page was saved instead of the model Delete the file and use the direct download link (…/resolve/main/<file>.gguf)
URL returned an HTML page when adding a GGUF A model page address was pasted Use the direct download link
A Claude or Codex model is missing from the picker The CLI is not on Kaptain's PATH Check which claude; add its folder in Settings › Runtimes › Toolchain Paths
gemini-cli support is disabled in this build The Gemini CLI is not a model in 0.0.9 Pick another model
"This Claude engine is too old for the model (…) — … — update Kaptain, or pick an older Claude model in Settings", then the turn fails The Claude helper built into this Kaptain does not know the Claude model you chose kaptain update and restart, or choose an older Claude model under Model in the ⚙ for claude-cli
cloud model … selected but no cloud base URL is configured The cloud model's settings are incomplete Add it again under + Add a model… › Cloud API
no vision model available No model that can see images is chosen or installed Choose one under Settings › Model Handling › Vision tool
An image description times out A slow vision model on a small GPU Set KAPTAIN_VISION_TIMEOUT_S higher, or pick a faster vision model
The chat's context card says summarised without a model (none can chat) — pick a summary model in Settings No model here can write the summary, so older messages were folded as plain text Choose a model under Settings › Model Handling › Context & Compaction or Delegation
A small local model loses track or runs out of room Its context window is the 8,192-token default Raise Context window in the ⚙ model settings, as memory allows
no worker model chosen — pick one in Settings ▸ Delegation No worker is chosen; there is no default Choose one under Settings › Model Handling › Delegation and press Save
Delegation does nothing Delegate is off, or the worker is not installed Turn on Tools and Delegate; choose a worker you have

Turns that stop or end early#

A turn that stops says why, in its row or under the answer (Run status). The name in brackets is the limit that ended it.

The chat says Cause Fix
STOPPED stopped by the user: Stop was pressed You, or another of your devices, pressed Stop Send the message again
STOPPED client disconnected: … or Kaptain shut down: … The browser went away, or Kaptain stopped, while the turn ran Send it again; a scheduled run waits for its next slot
ERROR stall guard: no model output or tool progress for 12m0s (stall_timeout) The model or a tool went silent for 12 minutes, for example a model still loading on a slow machine Check the model with kaptain doctor; raise stall_timeout_seconds in kaptain.json for a slow machine
ERROR agent turn timeout: the agent run reached 2h0m0s (agent_turn_timeout_seconds) A kapsule run took longer than its limit (2 hours unless agent_turn_timeout_seconds sets another) Raise agent_turn_timeout_seconds, or give the kapsule a smaller job
A note tool-round budget reached (50 rounds) — answering with what has been gathered, then an answer from what it had The model kept calling tools and never said it was done Ask a narrower question; raise max_tool_rounds only for long jobs
A note context window nearly full (…) — answering with what has been gathered The model's window filled with history and tool results Raise Context window in the ⚙ model settings, or start a new chat
Incomplete — 1 change failed and is not in place: … A file change or command the model made failed Read the named change in the turn's tool calls, then ask again
Not verified — the review could not judge the answer … Kaptain could not check the answer against what the run did Read the tool calls yourself before you rely on it

Tools, kapsules and MCP#

Symptom Cause Fix
A tool says User denied the operation though you did not The model is in Read-only, or kaptain-engine runs outside Kaptain, where changes are refused Change Tool approval, or use the CLI as a model inside Kaptain (MCP)
This run is unattended — no one is available to approve it A scheduled run on Ask reached a risky step Set the kapsule's Permissions to Auto-approve or Full access if it should act alone (Kapsule settings)
refused: path_not_allowed — … is outside every folder this kapsule may change The kapsule may change only its workspace and the folders you listed for it Add the folder under Settings › Edit access › Folders this kapsule may change, or path:/that/folder rw to its trusted scopes; writes there follow its approval mode (What a kapsule may write)
sandbox mode runs nothing privileged The model is in Read-only and the command used sudo Change its Tool approval if it should be asked for sudo
A command keeps running after the answer It outran its time limit or started a server, and became a background job Press Stop in the strip above the message box, or ask the model to stop it
refused: definition_read_only — … this kapsule can never change its own definition The write was into the kapsule's own kapsule.json or definition folder, which no kapsule changes, even inside a folder you granted Change the kapsule from its Settings, or ask Kaptain chat (Edit access)
A scheduled run did not happen Kaptain was not running when it was due (missed runs are skipped), the kapsule has no standing task, or it is disabled Check Jobs; add a task; enable the kapsule
A kapsule.json edit does not show up Hand edits are read at start Restart Kaptain
An MCP server is refused when added Its command is not installed Install the server's runtime, or give the full path to the program
An MCP server's key ended up in mcp_servers.json ${VAR} was not quoted, so the shell replaced it Remove and add the server again with 'KEY=${VAR}' in single quotes
Windows: model commands lack common tools No Git Bash, so commands run in cmd.exe Install portable Git Bash in Settings › Runtimes › Agent Shell (Windows)
sudo requests are turned off in Settings ▸ Sudo requests, so this command was not run The Sudo requests switch is off Turn it on under Settings › Model Handling › Sudo requests; every sudo then shows a pop-up for you to answer
timed out after 30s and was stopped The command ran through kaptain mcp (Claude Code or Codex), where commands stop at their time limit, or the chat already runs 8 background commands Ask for a longer timeout (up to 300 seconds), or stop a background command first
A background command ends with limit for background commands A command that outran its time limit ran longer than shell_job_max_minutes (default 60) Raise shell_job_max_minutes in kaptain.json, or start the command with background: true, which has no limit

Glossary#

Term Meaning
Access code chynj_…. Signs a person's browser or app into one Kaptain. Shown once at setup.
Trusted scopes A kapsule's named targets: folders it may change (rw, under its approval mode) or read without asking (ro), MCP servers it may use without asking, and the web hosts it is limited to. They never widen a permission mode.
Approval mode Ask, Read-only, Auto-approve in workspace or Full access: what tools may do without asking.
BlackBox The record of every turn: context sent, tool calls, reply and tokens.
Brain Logs Kaptain's live activity log in the workbench.
Channel Your own bot on Telegram, Signal, Discord or Slack, run from your machine.
CLI harness Claude Code or Codex driven by Kaptain as a model (claude-cli, codex-cli).
Compaction Folding older messages of a long chat into a summary, so it fits the model's window.
Connection code kcat_…. Lets another of your Kaptains use this one's models, and nothing else.
Data folder Where Kaptain keeps its settings, chats and models database.
Delegation Handing bounded work from the chat model to the worker model.
Device certificate Proof that a machine may use your licence.
Deview The file explorer and editor in the workbench.
Entitlement A short-lived signed proof of your licence, refreshed in the background.
GGUF The file format of models run by llama.cpp.
Job A command that keeps running in the background after its tool call returned, shown in the strip above the message box.
God's Eye The graph view of your project's code.
Kapsule An agent defined as a folder: model, persona, tools, permissions, memory and schedule.
KodeGraph Kaptain's index of your project's code, used by the code-search tools.
Krew Kaptain's toolbelt, and the workbench view that manages tools, MCP servers and skills.
Lesson A one-sentence rule a kapsule keeps with the remember tool after a clean run.
MCP Model Context Protocol, the open standard for connecting tools to models.
Node Another of your Kaptains whose models you borrow; its models show as node:<machine>/<model>.
Project folder The folder Kaptain and its tools work in.
Run memory Whether a scheduled kapsule replays its own past runs. Off by default.
Skill A Markdown document a model loads when relevant.
Summarizer The model that writes compaction summaries.
Tailnet Your private Tailscale network.
Tool resolver How tools reach a local or cloud model: a few in full, the rest by name, looked up with tool_schema_resolve when needed. Always on.
Worker Two uses: the worker model runs delegated briefs; a kapsule's workers are agents it creates for one job.