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.
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.
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.
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.
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.
One page. Every topic lives here once. Press / to filter the contents, or search the page with your browser.
Version 0.0.9. Everything here is true for Kaptain 0.0.9. The page is updated when a new version ships; the release notes list what changed.
Commands. Lines starting with $ are commands. The Copy button copies the commands only, never the prompt or the output.
Output. Output blocks show what Kaptain prints on Linux. Names, paths, process ids and numbers will differ on your machine.
Values are examples, not rules. Kaptain is built to be configured. Where a page shows a value, it is the default or one person's choice. The Settings reference says what each setting does so you can choose for your own machine and work.
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-smLinux 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.
Kaptain itself needs the binary, plus about 180 MB of disk if you choose Kaptain's built-in code search, more on a machine with a GPU, where it downloads a GPU build of llama.cpp (see Start Kaptain).
A CLI harness or a cloud model needs nothing else on this machine.
Local models need memory for the model. The setup wizard's starter models are the Qwen3.5 family, from 0.8B (a 1.3 GB download through Ollama) to 122B-A10B (81.4 GB). The wizard measures this machine's memory, marks each model Fits this machine or Needs more memory, and recommends the largest one that fits.
A GPU is optional. NVIDIA, AMD and Apple GPUs are detected and used automatically, by Ollama and by the llama.cpp build Kaptain downloads for GGUF files (GGUF). Everything also runs on the CPU, more slowly.
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:
Detects your platform with uname, and stops with a clear message on one that has no build.
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.
Downloads the build to a temporary file next to the destination, and checks its size and SHA-256 against the signed manifest.
Runs the checked binary once. If any check fails, the download is deleted, any existing Kaptain is left untouched, and the installer says why.
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.
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.
If the installer printed "Add Kaptain to your PATH", do the PATH step next, or kaptain will not be found.
To update later, run the installer again: it updates Kaptain to the newest published build. If that version is already installed it says already installed (verified) — nothing to change; to install it again anyway, run curl -sL https://chynj.ca/install.sh | KAPTAIN_REINSTALL=1 sh.
Without the installer: download the build from the table above, then:
The browser saves the file under its build name, such as kaptain-linux-x64. Rename it to kaptain and keep it in a folder you own.
kaptain update replaces the binary where it is, and kaptain uninstall looks for a file named kaptain. A copy moved into /usr/local/bin with sudo can be neither updated nor removed by Kaptain.
You should see the same output as on Linux, with Platform : Darwin / arm64 on Apple silicon or Darwin / x86_64 on Intel.
The Release line says signature verified (ssh-keygen), because macOS's own openssl cannot check this signature.
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:
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:
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.
Windows SmartScreen may say "Windows protected your PC", because the build is not yet signed. Choose More info, then Run anyway. This happens once.
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.
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.
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.
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.
You should see the version name of this build on the first line. The second line says whether this build carries the helper Kaptain uses to run Claude; kaptain sidecar check tests that it runs on this machine. kaptain --version and kaptain -v print the same.
If the shell says command not found, do the PATH step.
If an older kaptain answers, another copy earlier on your PATH shadows it: type -a kaptain lists every copy the shell can see.
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.
Do. Open a terminal in your home folder, or in the project you want to work in, and run kaptain start.
You should see. The lines above, then your browser opening on the setup wizard. kaptain start waits up to 30 seconds for the web interface to answer before it opens the browser.
If nothing happens.
command not found: Kaptain is not on your PATH yet. Do the PATH step, or run ~/.local/bin/kaptain start.
The browser did not open: open the UI: address it printed, http://127.0.0.1:8810, yourself.
Why.kaptain start runs Kaptain in the background, in its own session, so closing the terminal does not stop it. A fresh install lands on the setup wizard.
What Kaptain does on its own around the first start:
It may start Ollama.
If Ollama is installed but not answering, Kaptain starts it.
An Ollama that is already running is never reconfigured or restarted, and Kaptain only ever stops an Ollama it started itself.
Kaptain never installs Ollama on its own; on Linux it offers Install Ollama for me in the setup wizard and in Settings.
It downloads nothing for code search until you choose.
The setup wizard asks how code search should work (or you choose later under Settings › Model Handling › KodeGraph Embedder).
With Kaptain's built-in runtime, it downloads llama.cpp release b10106 for this machine (from the llama.cpp releases on GitHub: about 20 to 60 MB for the CPU build, more for a GPU build) and the nomic-embed-text model (146 MB, from Hugging Face) into the data folder, about 180 MB in all with the CPU build.
A llama-server you installed yourself (build 6000 or newer) is used instead of the llama.cpp download.
If the downloaded build cannot start because a system library is missing, Install llama.cpp now under Settings › Model Handling › KodeGraph Embedder names the library and offers to install it.
Choosing Ollama, None or a custom endpoint downloads nothing. Without an embedder, KodeGraph ranks by keywords.
KAPTAIN_EMBED_PREPROVISION=0 stops every background code-search download.
It may pull an embedding model into Ollama, but only if you chose Ollama for code search and Ollama has none. It pulls nomic-embed-text.
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 wizard runs once in your browser, and everything it sets can be changed later in Settings.
The progress bar shows seven steps; the install step appears only when something is downloading.
Every step from the second to the network step has ← Back.
If you refresh the page, the wizard comes back to the first step you have not finished, still tracking any downloads.
Each step below says what to do, what you should see, what to do if nothing happens, and why the step is there.
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).
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.
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.
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.
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.
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.
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.
What it is.chynj_ followed by 48 characters, shown once on the done screen, with a copy saved to access-code.txt in the data folder, readable only by your user. Copy it somewhere safe.
What it is for. Any other browser or device asks for it before it can use this Kaptain. CHYNJ never receives or stores the code itself, only a salted hash of it.
Whose it is. The access code belongs to this Kaptain, not to your CHYNJ account. You sign in to your CHYNJ account at chynj.ca or in setup; that is how the machine gets its licence. There is no sign-in to Kaptain itself: a browser reaches this Kaptain on this machine, or over your tailnet, with the access code. Connection codes for lending models are issued from it in Settings.
Open Kaptain signs this browser in, for 14 days at a time. In Local only mode the done screen says to open http://127.0.0.1:8810 in a browser on this machine. In Tailscale mode it shows One restart to finish with Restart Kaptain now, because the tailnet address answers only after the restart.
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.
When. The code may have leaked, or you want to sign out every browser at once.
Where. In Settings, or in a terminal on the computer where Kaptain runs. Kaptain does not need a restart either way.
In Settings
Do. Open Settings › Network Access › New access code, type the current code and press New access code.
You should see. The new code once, with Copy. It is saved to access-code.txt, and the browser you used stays paired.
If it is refused. Typing the current code is the confirmation: a wrong code changes nothing, and after a few wrong tries in a minute Kaptain asks you to wait.
In a terminal
Do. Run kaptain access-code rotate. It asks for no current code, because whoever can run it on this computer can already read kaptain.json.
You should see. The new code, printed once:
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
The old code stops at once. Every other browser and device paired with it, tabs already open included, shows Pair this browser with Kaptain and needs the new code; scripts that send the old code get 401.
Connection codes you issued to other Kaptains keep working: they are separate credentials, and each one is cancelled on its own under Settings › Network Access.
Kaptain serves only with a code it made
Once setup is done, a code that is empty, shorter than 32 characters after chynj_, or has characters a generated code never has is refused.
kaptain start and kaptain serve stop with one line naming the file and the way back, kaptain status shows the same line, and every request gets 401 with access_code_refused:
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
The way back: run kaptain access-code rotate, then kaptain start.
By hand, as a fallback. If you cannot run kaptain on that computer, put a generated code in place yourself:
Stop Kaptain: kaptain stop.
Make a code of the shape Kaptain makes. On Linux or macOS, this prints one; copy it:
Terminal
$ echo"chynj_$(openssl rand -hex 24)"
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.
Start Kaptain: kaptain start.
Pair every browser and the app again. Each one shows Pair this browser with Kaptain; enter the new code.
The access code is this Kaptain's own. It is not your CHYNJ account and not its password: a new access code changes nothing in your account, and changing your account password does not change the access code.
kaptain device register keeps the access code: it registers the machine through an approval at chynj.ca and changes nothing paired.
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:
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.
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.
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.
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.
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.
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).
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)."
In a browser that is already paired with this Kaptain, open http://127.0.0.1:8810/?force_setup=1 (or your tailnet address with /?force_setup=1). The wizard opens again with the choices on record filled in, including the network mode.
In a terminal, stop Kaptain and run kaptain setup --force.
Either way your access code, device and licence stay the same. To change one setting, use Settings instead.
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.
Setup is done and Kaptain is running. This is the path from an empty screen to a model doing work in your project folder.
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.
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.
Ask something. Type a question and press Enter. With Tools off, this is a plain conversation: fast, and nothing on your computer is touched.
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.
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.
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).
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:
Between local and cloud models, the new model gets the same conversation, with the summary of older messages if the chat was compacted.
To Claude or Codex, the CLI starts its own thread from the conversation and any earlier summary.
From Claude or Codex to another model, the CLI first writes a hand-over summary of its own thread (cards EXPORTING CLI CONTEXT, then CLI HANDOFF READY), and the last three messages go across word for word. A short chat, under 4 messages or 4,000 characters, goes across word for word with no summary. Settings › Model Handling › Context & Compaction › Handoff written by chooses who writes the summary. If it fails, CLI HANDOFF FAILED says why and the new model is not called.
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.
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:
Kaptain saves the whole result, in the run's record and as a file in results/<session>/ in the data folder.
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.
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 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.
Pick a model from the picker. It lists every model Kaptain can reach, grouped by route, and remembers your choice in this browser. If no model has been chosen yet, it says Choose a model. + Add a model… at the bottom adds Ollama, GGUF and cloud models.
Tools lets the model use Krew tools in this chat. Delegate lets it hand bounded work to the worker model; it needs Tools on.
Type / for commands and installed skills. Skills also open from a / in the middle of a sentence; commands such as /new work only at the start. A Claude or Codex model also lists that CLI's own skills.
Attach files with the paperclip. A model that cannot see images can have one described by the vision tool.
Steer a running turn. On a local or cloud model, a message you send while the model works joins the running turn instead of waiting for it to end.
Every turn's tool calls fold under its answer, and Show result lays each result out field by field. Older tool-heavy turns load as one line you can open, so long chats open quickly.
A failed run says why in the chat, with Retry to send the same message to the same model again.
Questions come to you. When a model needs a decision, including Claude's and Codex's own questions, a question card opens. Skip — you decide tells the model to choose and say what it assumed.
Links on this machine are checked. When a reply from a local or cloud model points at an address on this machine or your own network, such as http://localhost:8080, Kaptain opens it before the answer goes out. A link that still does not answer gets a line under the reply, such as "✗ Kaptain checked http://localhost:8080 — not reachable: connection refused (nothing is listening there)."
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.
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.
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.
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.
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.
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:
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:
Model chooses the model the CLI runs. CLI default uses the CLI's own setting. Claude offers Fable, Opus, Sonnet and Haiku (always the latest of each); Codex lists the models from its own catalogue.
Reasoning effort offers the levels the installed CLI supports. For Claude that is low, medium, high, xhigh and max; Codex levels depend on the model.
Tool approval maps onto the CLI's own permission modes:
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.
any endpoint that speaks the OpenAI chat-completions format
Model ID is the exact id your account has; Kaptain does not guess a catalogue. The model appears in the picker as cloud:<id>.
API key is stored in models.db in your data folder and never sent back to the browser.
Model size, the capability boxes (reasoning, vision, prompt cache, parallel tool calls, JSON mode, structured output, assistant prefill), Context window (128,000 by default) and Max output (4,096 by default) tell Kaptain how to use the model. Declare a smaller window and Kaptain sends less history.
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.
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.
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).
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:
Automatic uses your chat model if it can see images, otherwise the first Ollama model that declares vision.
A local model that declares vision, or a GGUF with its projector.
A cloud model. Cloud models are tried even when vision was not declared.
A Claude or Codex CLI, which looks at the picture with its own tools.
A model on a paired machine, which describes the picture there and sends back the words.
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.
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 doctorKaptain 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 0mschat 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.
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.
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.
A kapsule that writes a short digest every morning, from nothing:
Open Kapsules and press + New kapsule.
Give it a Name, such as news-digest. Write one line under Purpose and press Generate persona, or write the Persona yourself.
Choose a Model. A small local model is enough for a digest; leave it on engine default to use Kaptain's default model.
Under Schedule, choose Every day at a set time and a Time in your local time, or an interval such as Every 6 hours.
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.
Press Create kapsule. It is live at once.
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).
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).
One job each. Specific enough to judge: "summarize last night's logs", "draft release notes from the changelog". If two jobs need different tools or different review rules, make two kapsules.
Pick the model for the job. A small local model is fine for watching and summarizing; give judgement-heavy work your strongest route.
Bound the workspace. The agent reads your project but, by default, writes only in its own workspace, .kaptain/kapsules/<name>/ inside the project folder, under its permission mode. Any other folder, the project folder too, has to be added under Settings › Edit access › Folders this kapsule may change. It can never change its own definition, kapsule.json and its files in the data folder, even inside a folder you granted (What a kapsule may write).
Decide what unattended means. The permission mode is the real decision for a scheduled kapsule (below).
Read its first runs. Check the first scheduled results in Jobs and in BlackBox before trusting a schedule.
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.
path:<folder> rw gives the kapsule that folder to change, for every tool. It is the same grant as an external path and shows in the same list, Settings › Edit access › Folders this kapsule may change. How it writes there follows its approval mode: Full access or Auto-approve does it, Ask asks you first, Read-only refuses. Any folder you choose is allowed, your home folder too; / and folders inside Kaptain's data folder are refused when you save.
path:<folder> ro (the default when you leave the access off) lets it read that folder without asking.
mcp:<server id> lets the kapsule use that MCP server's tools without a prompt. Write the server's id: mcp- followed by the name you gave it, such as mcp:mcp-github, or kapsule-<name> for a kapsule's own server.
host:<domain>restricts web tools: once any host: entry exists, the kapsule may fetch only those hosts and their subdomains.
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> rwtrusted 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.
How it writes there follows your approval mode. In its workspace and in every folder you listed: Full access or Auto-approve, it does it; Ask, it asks you first; Read-only, it refuses. No folder skips the approval mode.
Any folder you choose is allowed, your home folder too. If you give a kapsule your whole projects folder, it works there the way its approval mode allows.
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. A write there is refused (definition_read_only) on every path, file tools, patches, delegated files and shell commands alike, and written to the Brain Log. Changing its task, tools, model, schedule or folders through kapsule_edit is refused too (self_edit_refused).
Kaptain chat, your own session, may create and change any kapsule. Ask it in plain words; it uses the agent-creation skill and the kapsule_create and kapsule_edit tools. Every change goes through your permission mode first: on Ask you approve it before anything is written.
Another kapsule's workspace stays closed to a kapsule, even inside the project folder or a folder you granted, unless that kapsule is ticked under Can edit kapsules.
A kapsule that may edit others can hand them only what it holds itself: a tool it has, a folder it may change, a kapsule it may edit. A kapsule it creates runs under its own permission mode. Delegate and card workers never change a kapsule's definition.
Kapsules you made before this rule get nothing added. If one used to write in the project folder, its next write there is refused with path_not_allowed, naming the file and Settings › Edit access › Folders this kapsule may change, and the refusal is written to the Brain Log. Add the project folder there if it should keep doing that work. Kaptain chat, your own session, writes in the project as before.
A trusted scope no longer skips the prompt. Before, a rw trusted scope let a kapsule on Ask write there without asking. Now it asks like every other folder; set the kapsule to Auto-approve or Full access if it should write there unattended.
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.
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
The time zone is an IANA name such as America/Toronto in schedule_tz; the create form fills in your browser's. Empty means this machine's zone. Interval schedules ignore it.
The shortest interval is 1 minute. A schedule needs a standing task.
Each occurrence runs at most once. If Kaptain was not running when a run was due, that run is skipped, not caught up, so a laptop that sleeps never fires a burst of make-up runs.
The same kapsule never runs twice at once. At most two different local models run scheduled jobs at once by default; change that under Scheduled Agents & Local Models in Settings.
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.
By default an agent cannot call another. A kapsule may call another when:
its Tools include agent_<name> for that kapsule, or
its Delegation is On (auto) or On (aggressive). With no names listed in allow_agents, that means any kapsule.
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.
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.
{"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)
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.
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.
When two skills share a name, the first source in this list wins:
The project:.kaptain/skills, .claude/skills and .agents/skills in the project folder. These follow the project as it changes.
This machine:skills/ in the data folder, where the Krew view and kaptain skill add put them.
Kapsules: the skill folders a kapsule ships with.
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.
Imported folders listed in KAPTAIN_SKILL_IMPORT_ROOTS.
Kaptain's own: skills built into Kaptain, such as agent-creation.
Krew › Skills › + Add skill writes a new one: name, description and instructions.
Import… installs from a folder, a .zip, a git URL or a GitHub owner/repo. Upload .zip takes a file. Every SKILL.md found is installed.
Drop a folder with a SKILL.md into any of the locations above. There is no registration step.
Terminal
$ kaptain skill add ./release-notes-skillinstalled release-notes 1 file(s) → /home/you/.local/share/kaptain/skills/release-notes/SKILL.md$ kaptain skill listrelease-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.
On their own. Models call skill_list to see what exists and skill_load to read one. Sharp names and descriptions get used without being asked.
For one turn. Type / in the chat and choose a skill. It shows as a chip and applies to that message only.
Always. A kapsule's Skills list weaves those skills into its instructions on every turn. Use this for rules that always apply, and skill_load for the ones that sometimes do.
What a model may do on your computer is decided by five things, and all five are yours to set:
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.
Its approval mode (below): Ask, Read-only, Auto-approve in workspace or Full access.
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).
Sudo, which is one switch, and every sudo shows you a pop-up (below).
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.
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.
Every tool call that could change something passes one approval gate. Each model has a mode, and each kapsule can set its own:
For a model: open the ⚙ next to the model picker and choose Tool approval. It applies from the next message, for that model.
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:
Reading inside the project never asks. Code search, reading files, web lookups, skills and memory run freely.
Read-only shell commands never ask. A command such as ls, cat, grep, git status or git diff, without redirection or substitution, runs at once in every mode. Everything else asks in Ask mode.
Tests always ask in Ask mode, even for a safe command.
Writing outside the project is refused in every mode, except a kapsule's own workspace and the folders you listed for it, external paths and rwtrusted scopes, where its approval mode decides (What a kapsule may write). Writing in Kaptain's data folder is always refused. Reading outside the project asks.
Every sudo asks you, in every mode except Read-only, where nothing privileged runs. Sudo is one switch, Settings › Model Handling › Sudo requests › Ask me for my password, on by default, and with it on every sudo opens a pop-up, whoever runs it: a local or cloud model, Claude Code or Codex, or a program a model started. The pop-up names the command (sudo: <command>, and which program asked) and has one field, Administrator (sudo) password — used once, never stored, with Cancel and Run with password. The password goes only to sudo on this computer, never to a model, a transcript or a file. It is remembered for the rest of that task, 2 minutes by default (0 to type it every time, at most 30), so later pop-ups in the task need one click; every sudo still shows a pop-up. Turn the switch off and sudo commands are not run, and the model is told why. A program that calls sudo by its full path, such as /usr/bin/sudo, is not stopped for the pop-up first; it reaches one only if sudo itself asks for the password. There is no sudo on Windows.
Tools from MCP servers ask on every call in Ask mode, read-only or not, unless a kapsule pre-approves the server. In Read-only, every MCP tool call is refused, even one that only reads, unless a kapsule pre-approves the server.
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.
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.
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.
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:
Connect it as an MCP server in Krew › MCP Servers or with kaptain mcp add (MCP).
Ship it inside a kapsule with the kapsule's mcp entry, so the tools, the agent and its skills travel as one folder.
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 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.
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:
+ Add from JSON takes the {"mcpServers": {...}} block from the server's README, as is: "Paste the server's own config block. Kaptain reads the standard shape, so a README snippet works as-is — local (command/args/env) or remote (url/headers), one server or several."
Add manually takes a name (lowercase), then either a local command with arguments or a remote URL, and one KEY=VALUE per line: environment variables for a local server, headers for a remote one. How does this server authenticate? offers OAuth sign-in for servers that need it.
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-mcpadded tavily (stdio) Kaptain is not running; it will connect on next start$ kaptain mcp add linear --url https://mcp.linear.app/mcp --oauthadded linear (http) Kaptain is not running; it will connect on next start$ kaptain mcp listlinear http enabled https://mcp.linear.app/mcp · oauthtavily stdio enabled npx -y tavily-mcp
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.
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.
Install Docker and check that docker run hello-world works for your user.
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.
Start Kaptain with the token in its environment. In the terminal you start Kaptain from, read the token without showing it, then restart:
Terminal
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.
Add the server. In Krew › MCP Servers, press + Add from JSON and paste:
GitHub MCP server
Kaptain saves ${GH_PAT} as written and fills in the value each time it starts the server.
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.
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.jsonadded github (stdio) Kaptain is not running; it will connect on next start$ kaptain mcp listgithub 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.
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.
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.
On the server's row, press Sign in. A new tab opens the vendor's page asking you to approve the connection.
Approve it. The tab then goes to a local address that does not load; that is expected.
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.
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 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.
{"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 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.
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:
Context sent: the context window and budget, the instructions, the messages and the tools that went to the model. For Claude and Codex it shows what was actually sent to the CLI and why: continuing the thread, handing it over with a summary, or starting fresh.
Each tool call, with its request and response.
The reply, and the error if there was one.
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.
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:
Context passed: every part the model was handed, with its size. The instructions, the operating brief, the environment, About this run (the date and time, and the address you opened Kaptain on), a kapsule's lessons, the tool definitions, the summary of older messages, the earlier messages, tool calls carried from earlier turns, and your message. View opens a part of the instructions exactly as it was sent.
Tool calls: each call with the size of what it sent and got back, how long it took, and whether it was refused. Result opens the result.
Model rounds with tokens in and out and how long the model took to read and write; the quality gates' decisions and the review; the answer's size; the tokens; and how the run ended, with the reason when it did not finish.
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.
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:
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 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.
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 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.
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.
Message your bot. It answers with a pairing code, because it does not know you yet.
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
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.
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.
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.
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.
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.
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.
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.
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.
Kaptain's security comes from a few blunt decisions rather than subtle ones.
Local first. Kaptain, your chats, keys and files live on your machine. No Kaptain cloud sees your prompts. CHYNJ's servers hold account and licensing records; your device is known to them by a hash of its fingerprint.
No internet exposure by default. The network mode is this machine or your own Tailscale network; no other mode is offered. The operator override KAPTAIN_ADDR can bind another address, but every request is still refused unless it comes from this machine, from your tailnet in Tailscale mode, or from a range you add to allowed_client_cidrs.
One gate for every risky action. Built-in tools, MCP tools and shell commands all pass the same approval gate, with the same approval modes. Read-only shell commands run without a prompt, so you are not asked about every ls.
Scopes name targets, never tools. A kapsule can be pre-approved for a folder or one MCP server. The approval mode stays the ceiling.
Three codes, three jobs. The access code (chynj_…) signs a person into this Kaptain. A connection code (kcat_…) lets another of your Kaptains use this one's models, and nothing else. The device certificate identifies this machine to the licence server. None can stand in for another.
Messages are data. Text that arrives from another agent, another machine or a channel is material to reason about, never an instruction carrying the receiver's authority. Authority comes only from the receiving kapsule's own settings.
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#
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.
Switch Kaptain to Tailscale: Settings › Network Access › Tailscale, or kaptain remote on in a terminal (below).
Restart Kaptain: Restart Kaptain now in Settings, or kaptain stop, then kaptain start.
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 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.
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.
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.
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:
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.
Keep Kaptain in Localhost only mode. Serve connects to Kaptain from this machine, which Tailscale mode refuses.
Publish Kaptain on the tailnet: tailscale serve --bg 8810.
Allow the name. Add it to allowed_hosts in kaptain.json. Kaptain picks it up within about 30 seconds:
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.
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.
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.
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.
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.
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.
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.
Create your CHYNJ account at chynj.ca, or in Kaptain's setup.
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.
The computer registers as a device and takes one seat of your plan's device limit.
CHYNJ issues the computer's licence, a signed lease that Kaptain renews on its own, and Kaptain starts working.
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.
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.
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.
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:
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.
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.
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.
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
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
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 noreplycode@chynj.ca; 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.
%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
.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
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.
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 from Settings › General › Update Kaptain (Check for updates, then Update now), or from a terminal:
Terminal
$ kaptain update --checkkaptain <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.
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:
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:
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.
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.
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.
One symbol's file, line and signature, and its source when asked.
When a model uses it: to fetch one function's source without reading the whole file.
Permission: Never asks.
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.
When a model uses it: before changing a function, to see who depends on it.
Permission: Never asks.
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.
When a model uses it: to trace what a function does downstream.
Permission: Never asks.
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.
When a model uses it: to judge the reach of a change before a refactor.
Permission: Never asks.
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.
When a model uses it: to get oriented in an unfamiliar project.
Index statistics and freshness, and live progress while an index pass runs.
When a model uses it: to check the index exists and is current.
Permission: Never asks.
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.
When a model uses it: in a new project, or after large changes.
Permission: Never asks. A home folder or a tree of more than 100,000 files is refused unless confirm is true.
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)
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.
When a model uses it: to see the exact text before editing it.
Permission: Never asks inside the project. Outside it: asks in Ask mode, runs in Auto-approve and Full access, refused in Read-only, and runs without asking when a trusted scope covers it.
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"}
file_search
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.
When a model uses it: to find the exact place to edit.
Permission: Never asks inside the project. Outside it: asks in Ask mode, runs in Auto-approve and Full access, refused in Read-only, and runs without asking when a trusted scope covers it.
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.
When a model uses it: for new files or full rewrites.
Permission: A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the folders you listed for it (external paths and rw trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (path_not_allowed), and its own definition never.
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.
When a model uses it: for targeted changes after reading the file.
Permission: A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the folders you listed for it (external paths and rw trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (path_not_allowed), and its own definition never.
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
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.
When a model uses it: for a change across several files expressed as one diff.
Permission: A change. Asks in Ask mode, refused in Read-only, runs in Auto-approve and Full access. Outside the project it is refused in every mode unless the folder is one a kapsule may change. A kapsule writes only in its workspace and the folders you listed for it (external paths and rw trusted scopes), under its approval mode; anywhere else, the project folder included, is refused (path_not_allowed), and its own definition never.
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.
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.
When a model uses it: to build, inspect the system, or run tools that have no dedicated Krew tool.
Permission: Read-only commands never ask: ls, cat, head, grep, rg, find, wc, diff, git status, git log, git diff and similar, alone or piped, without redirection, substitution or background jobs. Everything else is a change: it asks in Ask mode, is refused in Read-only, and runs in Auto-approve and Full access. Every sudo, also one inside a program the command starts, shows a pop-up where you allow it and type your password, whichever model runs it; with Settings › Sudo requests off, sudo commands are not run, and Read-only runs none. There is no sudo on Windows. shell_allow_project_tests adds pytest, go build, go vet, go test and npm test to the read-only list. Reading or stopping a job never asks.
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
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.
When a model uses it: to check a change.
Permission: Always a change: asks in Ask mode, even for a safe command; refused in Read-only.
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.
When a model uses it: to check status or diffs, or to commit when you ask.
Permission: Reading commands never ask: status, diff, log, show, rev-parse, ls-files, blame, shortlog, describe, and listing branch or remote. Everything else, and config, is a change.
Searches the web through DuckDuckGo and returns titles, addresses and snippets.
When a model uses it: for anything recent or outside the model's training.
Permission: Never asks. A kapsule's host: trusted scopes do not limit searching; they limit the tools that fetch an address.
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.
When a model uses it: to read a page found by search.
Permission: Never asks. If a kapsule lists any host: trusted scope, it may fetch only those hosts.
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.
When a model uses it: for APIs and JSON endpoints.
Permission: Never asks. If a kapsule lists any host: trusted scope, it may fetch only those hosts.
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.
When a model uses it: to summarize a page with its metadata.
Permission: Never asks. If a kapsule lists any host: trusted scope, it may fetch only those hosts.
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.
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.
When a model uses it: inside a kapsule run, when a reusable rule emerges. Outside a kapsule it is unavailable.
Permission: Never asks; it writes only the kapsule's own lesson store.
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.
When a model uses it: when a detail from earlier is no longer in view.
Permission: Never asks.
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.
When a model uses it: to finish reading a result that did not fit, or to look at an earlier turn's result again instead of running the tool again.
Permission: Never asks.
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.
Asks you one to four multiple-choice questions and waits for the answers.
When a model uses it: at a real fork the model cannot settle alone: a missing requirement, an unclear target, or a choice between safe and destructive.
Permission: Never asks for permission; it is a question.
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.
When a model uses it: before the first call to a tool it was shown only by name.
Permission: Never asks; it runs nothing.
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.
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.
When a model uses it: for bulk mechanical work: reading many files, extraction, first drafts.
Permission: Never asks for the call itself. Writing output_file is a change, as with file_write: it asks in Ask mode and is refused in Read-only, before any model runs. A worker given tools asks for its own changes the same way. Offered only when Delegate is on.
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.
When a model uses it: for independent mechanical tasks at once.
Permission: Writing its output files is a change: asks in Ask mode, refused in Read-only. Offered only when Delegate is on.
Reports the worker model, its size class and the limits of one brief.
When a model uses it: before sizing a delegate brief.
Permission: Never asks. Offered only when Delegate is on.
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)"}
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.
When a model uses it: on screenshots, diagrams and photos the chat model cannot see itself.
Permission: Never asks. A local file must be inside the project or a chat attachment; any other path 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.
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.
When a model uses it: in a kapsule with Can bring in workers on, when a job splits cleanly.
Permission: The call never asks. Workers never get more tools than the kapsule, and run unattended: by default they cannot make changes and report what they could not do.
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.
When a model uses it: when a kapsule is allowed to call another (agents calling agents).
Permission: No prompt; the calling kapsule's delegation settings decide, three levels deep at most.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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
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.
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
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
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
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
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
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.