How-To · 10 min

Install Kaptain

One binary per platform, no system services, no admin daemon. This page takes you from nothing to a running Kaptain and shows the four commands you will actually use.

1 · Pick your build

You run	Download
Linux (Intel/AMD)	linux-x64
Linux (ARM, e.g. Raspberry Pi)	linux-arm64
macOS (Apple Silicon)	macos-arm64
macOS (Intel)	macos-x64
Windows	win
Android phone (client app)	apk — pairs with a Kaptain running on one of the machines above

Not sure which Mac you have? Apple menu ▸ About This Mac — "Apple M…" means macos-arm64, an Intel processor means macos-x64. On Linux, uname -m: x86_64 → linux-x64, aarch64 → linux-arm64 (Raspberry Pi 4/5). The download dialog on the Kaptain page detects your platform and preselects the right one.

What the machine needs: Kaptain itself is light — one self-contained binary (about 60 MB; the Claude sidecar is embedded), no runtime, no interpreter, no package manager, a few hundred MB of memory. The real demands come from whichever model route you pick during setup, not before it: a CLI harness or a cloud key needs nothing local; Ollama wants ~8 GB RAM for a 4B model, ~16 GB for 12B; building llama.cpp additionally needs git and cmake. A discrete GPU is optional — CUDA, ROCm, Metal and Vulkan are detected and used; without one, models run on CPU, more slowly.

2 · Get the binary

Easiest (Linux/macOS): the terminal installer downloads the right build and puts kaptain on your PATH. It installs and stops — it never starts anything for you.

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

It detects the platform, downloads the matching build through chynj.ca/download, runs the new binary's --help as a smoke test (a broken download can never replace a working install), and installs to ~/.local/bin — never with sudo; if that folder isn't on your PATH it prints the exact export line. It installs only — it never starts Kaptain — so the command is safe inside Dockerfiles, CI images, and configuration management. Run it again any time to update: the swap is atomic and the old binary survives a failed smoke test. (The in-app updater is the one that verifies SHA-256 against the signed release manifest.)

Or by hand: download from the table above, make it executable, put it somewhere on your PATH:

The saved file is named plain kaptain on Linux and macOS, whichever build you picked (Windows keeps kaptain-windows-x64.exe):

chmod +x kaptain
mv kaptain ~/.local/bin/kaptain

Windows: download kaptain-windows-x64.exe, put it in a folder you like, double-click it — a no-terminal launch is treated as start: the server backgrounds itself and your browser opens. (In a terminal, the bare command kaptain prints the command list and exits — it never starts a server by surprise.)

First-launch confirmations: the binaries are not yet signed with an Apple or Microsoft certificate, so each OS asks once — a reaction to the missing signature, not to anything found in the file. macOS: Gatekeeper → Open Anyway (or clear the quarantine flag). Windows: SmartScreen → More info → Run anyway. Linux: just chmod +x.

Per-platform detail pages: Windows · macOS · Linux · terminal installer.

Verify before anything else:

kaptain --version

3 · Run it

kaptain start

This backgrounds the server in its own session (it survives closing the terminal), waits until the web interface actually answers, then opens your browser. First launch lands on the setup wizard — the Set up Kaptain guide walks every step.

The four commands

Command	What it does
`kaptain start`	Run detached. Survives the terminal closing; logs to `kaptain.log` in the data folder; opens the browser once the listener answers. The everyday command.
`kaptain serve`	Run in the foreground — dies with the terminal. For systemd units, debugging, scripts.
`kaptain stop`	Stop the running server. Finds it even if it wasn't started with `start`.
`kaptain status`	Is it running, where, and where the log lives.

Updating later

Settings ▸ General ▸ Update Kaptain (or kaptain update) downloads the published build, verifies its SHA-256 against the signed release manifest, smoke-tests the new binary, and atomically swaps it in place — your previous binary is kept next to it as .bak. The running server keeps executing the old version until you restart:

kaptain stop then kaptain start (one line on Linux/macOS: kaptain stop && kaptain start)

If it goes wrong

"command not found" — ~/.local/bin isn't on your PATH, or an older program named kaptain shadows it. type -a kaptain shows exactly what your shell resolves; the newest entry should be the binary you installed.
Browser didn't open — kaptain status prints the address; open it yourself.
Release build answers 402 — the machine isn't bound to your account yet: Fix a 402, one command and one click.

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