Install

Install Kin on Linux or Apple Silicon macOS, then run kin doctor and connect a model. Windows uses WSL2; Intel macOS is best-effort and may require native dependencies to build locally.

The one-liner (get.kinra.ai)

bash <(curl -fsSL https://get.kinra.ai/install.sh)
kin doctor

The installer page provides per-OS guidance and links the script and checksum for review. The script needs no sudo, leaves shell rc files alone, and installs uv if needed.

On a fresh machine it selects one of two paths:

• With Git and authorized GitHub SSH access, clone kinra-ai/kin to ~/kin, sync the locked environment, install editable, and write starter settings.
• Otherwise, install the public release wheel selected by Kinra’s manifest and SHA-256. Existing settings stay untouched; add credentials through /providers.

An existing ~/kin is treated as a checkout; an older ~/kin-textual is reused when ~/kin is absent. Unsafe or incomplete checkout state fails explicitly instead of switching install paths.

To inspect the decision tree without changing the machine or probing SSH:

bash <(curl -fsSL https://get.kinra.ai/install.sh) --check

For an intentional wheel install or rollback, substitute a retained VERSION:

uv tool install --reinstall \
  "kin @ https://get.kinra.ai/kin-VERSION-py3-none-any.whl" \
  --index https://pypi.org/simple/ \
  --default-index https://get.kinra.ai/simple/

Keep Kin as this direct same-origin requirement: PyPI also contains an unrelated package named kin. PyPI supplies third-party dependencies; the normal installer adds the published Kin wheel checksum automatically.

Prerequisites

Kin needs Python ≥3.11 and a model endpoint. The installer manages Python through uv. Anthropic, OpenAI, OpenRouter, and supported local servers are covered in models and providers.

Herdr is optional for terminal detach/reattach. Saved journals and kin --resume work without it.

From the checkout (by hand)

In an authorized checkout:

uv sync
uv run kin

Use uv run or the owning Task command for development so Kin uses the checkout’s pinned environment. Task is optional; task run wraps uv run kin.

Install as a tool

Choose the source you have:

# Authorized repository access
uv tool install git+ssh://git@github.com/kinra-ai/kin

# Editable local checkout
uv tool install --editable /path/to/kin

# Locally built wheel
uv build
uv tool install "./dist/kin-$(uv version --short)-py3-none-any.whl"

Plain kin then runs from any directory and uses that directory as its workspace unless you pass --workdir.

Editable installs track source changes, but new dependencies still require an environment refresh. kin update handles both; after a manual pull, use uv tool install --reinstall --editable <checkout> when dependencies change. If the wrong command runs, check type kin for a shadowing alias or function.

Verify the install

kin doctor checks command availability, configuration, provider resolution, and endpoint health. kin doctor --offline skips the endpoint probe. kin --version and kin --help confirm which command you installed. See the doctor reference for diagnostics, then first run for connection setup.

Updating

kin update

Checkout updates fast-forward, sync dependencies, and refresh the tool environment. Dirty or diverged checkouts fail with a recovery instruction. Wheel updates install the manifest-selected immutable wheel and checksum. kin update --check only reports; exit 1 means an update is available.

The TUI makes a best-effort update check at startup, cached for 24 hours. It sends the Kin version in its User-Agent and never updates automatically. Disable the check with KIN_UPDATE_CHECK=0 or update_check = false. After an update, the next launch shows release notes once.

If updating fails, rerun the installer, then use kin doctor for the remaining fix. Use the versioned wheel command above for a deliberate rollback.

Setting up a second machine

Install per machine. For matched development checkouts and shared non-secret settings, see multi-machine setup.