Document · Setup · 14 min read

Kaptain Setup Guide

Install Kaptain, complete first run, choose the workspace Kaptain can operate in, connect a model route, choose Local Only or Tailscale access, and verify the local runtime.

Overview

Kaptain is a local runtime. It starts a local web server, opens a browser interface, stores configuration on the user's machine, and works inside the project folder the user selects. It can optionally be reached from trusted devices through Tailscale.

The normal setup flow is: install Kaptain, start the server, open the browser interface, sign in or create a CHYNJ account, start the trial or enter a license key, choose a model runtime, select a project folder, choose who can reach Kaptain, and verify the runtime.

Pick the right build

Kaptain ships one self-contained binary per platform and architecture. Nothing else needs to be installed for Kaptain itself — there is no runtime, no interpreter, and no package manager involved.

The download dialog on the Kaptain page detects the platform and offers the matching build, with the rest one click away.

What the machine needs

Kaptain itself is light: roughly 18 MB on disk and a few hundred megabytes of memory. The demands come from whichever model runtime is chosen, and that choice is made during setup, not before it.

A discrete GPU is optional. Kaptain detects CUDA, ROCm, Metal and Vulkan and configures the local runtime accordingly; without one, models run on CPU, more slowly.

Install Kaptain

Two routes. The terminal installer is the fastest on macOS and Linux; the direct download works everywhere.

Terminal installer — macOS and Linux

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

It detects the platform, downloads the matching build, verifies its SHA-256 against the published manifest, and installs it to /usr/local/bin (or ~/.local/bin without sudo). It installs only — it does not start Kaptain. That is deliberate, so the command is safe inside Dockerfiles, CI images and configuration management. Full detail: Install from the terminal.

Direct download

Every build is available from https://chynj.ca/download/kaptain/<build>, using the build name from the table above.

Because the binaries are not yet signed with an Apple or Microsoft certificate, each operating system asks for confirmation the first time. That is a reaction to the missing signature, not to anything found in the file, and each platform has a one-time step:

• macOS — Gatekeeper: clear the quarantine flag, or use Open Anyway.
• Windows — SmartScreen: More info, then Run anyway.
• Linux — mark it executable with chmod +x.

Start the server

Start Kaptain with the start command:

kaptain start

It runs in the background, prints the URL, bind address and log file, and opens the browser interface at http://localhost:8810. Use kaptain status to check it and kaptain stop to shut it down.

Running the bare command kaptain with no arguments prints the list of available commands and exits — it does not start the server. On Windows the equivalent is .\kaptain.exe start, with one exception: double-clicking kaptain.exe in Explorer does start the server, because a double-clicked program has no terminal in which the command list could be read.

First run walks through setup

On a machine that has not been set up, Kaptain opens the setup wizard automatically. It has seven steps, shown as dots across the top:

1. Account — sign in to your CHYNJ account, or create one. The tabs are Sign in and Create account; sign-in also offers Forgot password?, and asks for a 6-digit code if the account has two-factor enabled. When your CHYNJ account service offers them, Continue with Google and Continue with GitHub appear below the sign-in form; they open your browser, and the wizard continues once the browser hands back. There is no skip: an account is required, though the trial itself stays free and card-free.
2. Plan — Kaptain checks what this device is entitled to and shows one of: Start Free Trial (3 days, no card, and the clock starts only when you press it), Continue Free Trial with the days remaining, License active, or Trial expired. Have a license key? reveals a field for a KAPTAIN-… key at any point.
3. Models — Kaptain detects the Claude and Codex CLIs, Ollama, and any local GGUF files, and reports the state of each. Claude CLI and Codex CLI have checkboxes and are mutually exclusive; a runtime that is not installed cannot be selected here. Whatever you pick becomes the default provider, and everything is changeable later in Settings.
4. Install — a progress screen for anything the previous step queued for download. Enabling a CLI harness queues nothing, so this step usually passes straight through.
5. Project — the folder Kaptain indexes and works in.
6. Network — Local only, or Remote + local — Tailscale. The Tailscale option is selectable only when Tailscale is detected on the machine, and is preselected when it is.
7. Done — Kaptain mints this device's access code, offers a link for connecting another device, and opens the interface.

Email verification is separate from the step list. Creating an account sends a verification email, and the account works immediately, but CHYNJ will not start a free trial for an unverified address. If the Plan step answers "Verify your email address to start your free trial", open the link in that email and press the button again. A paid license is unaffected.

The trial is bound to the device, so reinstalling does not start a second one, and subscribing later keeps everything configured here.

Choose the project folder deliberately

The project folder controls what Kaptain can read, plan against, and edit. For first use, start Kaptain from the intended project directory or confirm the project folder in the setup wizard.

During setup, Kaptain may create a .planning folder inside the selected project. That folder can hold project context, task board data, session notes, and related working state.

Connect a model provider

Kaptain is model agnostic. Depending on what is installed and configured, it can use CLI providers, local model runtimes, or configured API endpoints. Common routes include Claude Code CLI, OpenAI Codex CLI, Gemini CLI, Ollama, GGUF/llama.cpp routes, and custom OpenAI-compatible endpoints.

Use a strong model for ambiguous reasoning and final judgment. Use local, lighter, or cheaper routes only where the task is suitable and the result remains reviewable.

Large local model downloads can take time. After adding an Ollama or GGUF model, wait for the install to finish, then use the model refresh or GGUF scan controls if the model list has not updated yet.

Network access

The secure default is Local Only: localhost on the same machine. Other devices cannot reach Kaptain until the user intentionally enables trusted remote access.

For phone or second-device access, use Tailscale. Install Tailscale on the Kaptain machine and the second device, sign in to the same tailnet, then switch Network Access to Tailscale in Settings → Network & Security → Network Access and restart Kaptain.

There are exactly two network choices, named Local only in the setup wizard and Localhost only in Settings, and Tailscale. A plain LAN or public bind is refused by the binary. If older terminal output or an older config gives conflicting network guidance, update Kaptain and use the Network Access settings instead.

Verify the installation

• Run kaptain status. It prints the process id and the UI URL, or reports that Kaptain is stopped.
• Open http://localhost:8810 on the Kaptain machine.
• Confirm setup completes and a project folder is selected.
• Confirm the chosen model route appears under Settings → Models & Runtime.
• Send a small test message before enabling automatic workflows.
• To check the server from a script without pairing a browser: curl http://localhost:8810/api/setup/status. It answers {"needs_setup":false} once setup is finished. Every other API route requires this device's access code.
• If using Tailscale, connect through the Tailscale address shown by Kaptain and enter this device's access code (chynj_…) on the pairing screen.

Continue with the User Guide after setup succeeds.