How-To · 15 min

Set up Kaptain (the first-run wizard)

The wizard runs once, in your browser, in seven steps. Nothing here is a lock-in — every choice is changeable later in Settings. Two rules before you start: hover any (i) for a plain-words explanation, and save your access code when the done screen shows it.

1 · Account

Sign in to (or create) your CHYNJ account — the tabs are Sign in and Create account, sign-in offers Forgot password?, and accounts with two-factor are asked for their 6-digit code. Continue with Google / GitHub appear when the account service offers them. There is no skip: an account is required, though the trial itself stays free and card-free. Signing in here is what binds the machine to your licence — the device certificate enrolls automatically, so a release build starts entitled instead of asking later. Passwords need 12+ characters; Enter submits.

Email verification is separate from the step list: a new account works immediately, but the free trial won't start for an unverified address — if Plan answers "Verify your email address", open the link in the mail and press the button again. A paid licence is unaffected.

2 · Plan

Kaptain checks what this device is entitled to and shows exactly one of: Start Free Trial (3 days, no card — and the clock starts only when you press it), Continue Free Trial with days remaining, License active, or Trial expired. Have a license key? reveals a key field at any point (on an expired-trial machine it's already visible). Buttons stay disabled until the licence probe finishes, so a dead network can't click you into a broken state. The trial is bound to the device — reinstalling doesn't start a second one, and subscribing later keeps everything configured here.

Know the limit: pasting a licence key alone activates the plan but does not certify the device — signing in (step 1) or kaptain device register does. Details: Licences, devices & 402s.

3 · Models

The wizard detects what the machine already has — GPU, an installed Ollama (and whether it's running), llama.cpp and local GGUF files, Claude/Codex CLIs including their sign-in state — and offers routes accordingly. A runtime that isn't installed can't be selected; the Claude and Codex checkboxes are mutually exclusive here, and whatever you pick becomes the default provider (everything is changeable later in Settings). The Add models guide explains every type in depth. Rules of thumb: a CLI you already use is the lightest start; a 4B local model runs in ~8 GB of RAM, 12B wants ~16 GB.

4 · Install

Kaptain installs what it can do safely in user space, and only hints at what needs system privileges:

Failures show the real reason on the job row — nothing fails silently. Enabling only a CLI harness queues nothing, so this step usually passes straight through. Big local model downloads take time; if the model list hasn't caught up afterwards, the refresh / GGUF-scan controls bring it up to date.

5 · Project folder

Pick the folder Kaptain works inside — it reads, plans against, and edits there, nowhere else. Choose the project you want help with, not a home directory full of unrelated files. A blank field is refused rather than guessed. Setup adds exactly one thing inside: a .planning/ folder (project context + task board), and it never overwrites one that already exists.

6 · Network

Two modes, honestly described on the screen:

There are exactly two choices — a plain LAN or public bind is refused by the binary, and an unrecognised value can never silently downgrade security: anything else becomes Local only. (Settings calls the first mode Localhost only; same thing.)

7 · Done — the access code

The done screen shows your device access code (chynj_…) once, labelled save-it-now, with a Copy button, a connect link for pairing another device, and the connect address that is actually true for the mode you picked. This code is how every browser and phone signs in to this Kaptain. If you ever lose it, run kaptain device register on the machine — it mints a fresh code (and every paired device re-pairs once with the new one).

Then send one small chat message before wiring up anything automatic — see a working answer before you schedule one.

Re-running setup

Setup marks itself complete only when the wizard finishes — never merely because a token exists. To revisit it deliberately, open /?force_setup=1 on the Kaptain address. Every choice also lives in Settings, which is usually the better door.

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.