Install

Get the kin command onto your machine — one pasted command from get.kinra.ai, from a checkout for development, or installed as a standalone tool on your PATH.

The one-liner (get.kinra.ai)

The fastest path on a fresh Linux/macOS machine:

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

The Kin product page has per-OS guidance (Fedora / Ubuntu·Debian / macOS / Windows-via-WSL2). The script is idempotent, needs no sudo, and never edits shell rc files. It installs uv first when needed, then selects one of two fresh-machine paths:

• With Git and authorized GitHub SSH access, it clones the private kinra-ai/kin repository to ~/kin, syncs the locked environment, installs the command editable, and writes the shared starter ~/.kin/settings.toml.
• If Git is absent, SSH authorization is denied, or GitHub SSH is unreachable, it automatically installs or refreshes the public wheel. The installer reads Kinra’s release manifest and SHA-256, pins Kin itself to that immutable versioned wheel, and uses PyPI only for Kin’s public third-party dependencies. Wheel installs leave settings untouched; enter provider keys in Kin through /providers.

Read the script before running it: the page links the installer and its SHA-256.

If an older installer already created ~/kin-textual, reruns reuse that checkout in place when ~/kin is absent; the installer neither moves the working tree nor clones a duplicate. More importantly, an existing ~/kin or ~/kin-textual is always treated as a checkout install. Incomplete, malformed, or unsafe checkout state fails explicitly and is never bypassed through the wheel channel.

To walk the complete decision tree without probing SSH, writing known_hosts, or changing the machine:

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/

This is a product install with no checkout or development loop. Kin is a direct same-origin requirement, so the higher-priority PyPI dependency index cannot substitute the unrelated package also named kin. The normal installer adds the published SHA-256 automatically.

Verify any install with kin doctor:

kin doctor

Prerequisites

You need	Why
Python ≥ 3.11	The harness uses stdlib tomllib and 3.11+ typing.
uv	Environment + tool management. task sync is uv sync; the console script installs via uv tool.
A model endpoint	kin is a client — it needs a model to talk to. A local OpenAI-compat server (vLLM, llama.cpp), Anthropic, OpenAI, or OpenRouter all work — see Models & providers for the wire heuristic, or First run for the launch recipes.

Task (task) is convenient but optional — every task target maps to a plain command you can run directly.

From the checkout (by hand)

This is the development path: clone the repo, sync the environment, run.

uv sync     # .venv + the harness deps + an editable install of `kin`
task run    # launch the Textual UI against the in-process harness

task run is a thin wrapper over the installed console script. The raw equivalent is:

uv run kin

Run kin through uv run (or task run) from the checkout so it picks up the pinned Textual (≥ 8.2.7) in the .venv — the system python3 may carry an older one.

Install as a tool

kin is a normal installable package (src layout, hatchling, console script kin). To put the command on your PATH outside the checkout, use uv tool install.

From the repo

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

From a local wheel

uv build                                   # -> dist/kin-<version>-py3-none-any.whl + sdist
uv tool install "./dist/kin-$(uv version --short)-py3-none-any.whl"

Editable, from a checkout (active dev)

uv tool install --editable /path/to/kin

Plain kin (outside the checkout, no uv run needed) now tracks the checkout’s source live — no rebuild/reinstall cycle for code changes.

Then run kin from any directory; it operates on your current working directory unless you pass --workdir.

An editable tool install does NOT track new dependencies

--editable makes the tool’s venv follow your checkout’s source live — but the venv’s installed packages are only resolved against pyproject.toml/uv.lock at install time. Pulling a change that adds a new dependency does not get it into an already-installed tool venv; the symptom is narrow and confusing — everything that doesn’t touch the new dependency keeps working, and only the code path that imports it fails (as a ModuleNotFoundError at that exact call site, or worse, silently if that call site is inside a backgrounded worker). kin update closes this hole: its checkout path always refreshes the tool venv after pulling. Bare git pull users: run kin update (or uv tool install --reinstall --editable <checkout>) any time dependencies change, not just when you want fresh code.

Shell-alias shadowing

If you already have a shell alias or function named kin (for example one pointing at a different binary), comment it out — otherwise the alias wins and the installed command never runs. Check with type kin.

Verify the install

The first check on any machine is the doctor:

kin doctor      # tools on PATH, config parses + a provider resolves, endpoint answers

It exits 0 when everything critical passes and names the first fix to try otherwise (--offline skips the endpoint probe). See the CLI reference for the exact checks.

A standalone tool install has no checkout to run those against — there, kin doctor plus the command resolving is the confirmation:

kin --version
kin --help

You should see the launch flags (--provider, --model, --base-url, --workdir, --mode, --resume, and the sampling flags — the full list is in CLI flags). With that working, move on to First run to point kin at a model.

Updating

kin tells you when a new release is out: at session start the TUI makes one best-effort, 24h-cached check of https://get.kinra.ai/version.json and shows a one-line note when a newer release is published (privacy note: that request carries only your kin version in its User-Agent; opt out with update_check = false or KIN_UPDATE_CHECK=0). Nothing updates by itself — the update is one command:

kin update

It detects how kin was installed and does the right thing for that shape:

• Checkout install (an authorized get.kinra.ai branch / an editable uv tool install): git pull --ff-only in the checkout, uv sync, then a full tool-venv refresh — so a pulled dependency change lands too (the warning box above). A dirty or diverged checkout fails with the exact next step instead of touching your work.
• Wheel install (the normal public get.kinra.ai fallback): uv tool install --reinstall of the manifest-selected, SHA-256-pinned immutable Kin wheel, with PyPI available only for public third-party dependencies.

kin update --check reports without applying (exit 1 when an update is available — cron-friendly), and kin doctor includes the same staleness line.

Fallbacks, in order: kin update → re-run the get.kinra.ai one-liner (idempotent — it heals a half-updated install, including the tool venv) → kin doctor to name what’s still wrong. To roll back a wheel install, older releases stay installable: uv tool install --reinstall "kin @ https://get.kinra.ai/kin-0.2.0-py3-none-any.whl" --index https://pypi.org/simple/ --default-index https://get.kinra.ai/simple/; a checkout rolls back with git checkout v0.2.0.

Setting up a second machine

Ordinary installation is per machine. Maintainers who need a matched MacOS/kloud development setup, build-worktree separation, shared non-secret settings, and the kloud:* commands should follow Multi-machine setup.