Document · Setup · 14 min read

Kaptain Setup Guide

Install Kaptain, complete first run, choose the workspace Kaptain can operate in, connect a model route, 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 UI, sign in or create an account, activate trial or license access, select a project folder, connect a model provider, and verify the runtime.

Install Kaptain

Choose the install path that matches the user's operating system.

Linux or macOS

Install from the official CHYNJ installer:

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

The installer places the binary in the user's local bin path. If the terminal cannot find kaptain, add the local bin directory to PATH, then verify with:

kaptain version

Windows

Download the Windows build from the official CHYNJ download route:

https://chynj.ca/download/kaptain/win

Run the downloaded kaptain.exe. From PowerShell in the download folder, use:

.\kaptain.exe

Users who want terminal-wide access can place kaptain.exe in a folder already on PATH, or add the folder containing kaptain.exe to their user PATH.

Start the server

Start Kaptain from a terminal:

kaptain
kaptain serve

Kaptain opens at http://localhost:8888. Keep the terminal window open unless the installed package is configured as a background service.

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.

Operating rule: Do not select a folder that contains unrelated private data. Kaptain should be scoped to the project you actually want it to help operate.

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.

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 Remote+Local Tailscale. Kaptain does not ship a public LAN/all-interface mode in this build.

Verify the installation

Open http://localhost:8888 on the Kaptain machine.
Confirm setup completes and a project folder is selected.
Confirm the chosen model route appears in Model Settings.
Send a small test message before enabling automatic workflows.
Check the health endpoint locally with curl http://localhost:8888/health.
If using Tailscale, connect through the Tailscale address and current access token.

Continue with the User Guide after setup succeeds.