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 get.kinra.ai page has per-OS buttons (Fedora / Ubuntu·Debian / macOS / Windows-via-WSL2) with the native prereq for each. The script is idempotent, needs no sudo, and never edits your shell rc files: it installs uv if missing, clones kinra-ai/kin-textual to ~/kin-textual (an SSH key with repo access is required), installs the kin command via uv tool install --editable, and writes a starter ~/.kin/settings.toml — keys stay yours, entered in-app via /providers. Read it before you run it: the page links the script and its SHA256.

No SSH key? Install the latest built wheel instead — a read-only build, no checkout, no dev loop:

uv tool install kin --index https://get.kinra.ai/simple/

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 repoFrom a local wheelEditable, from a checkout (active dev)

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

uv build                                   # -> dist/kin-0.1.0-py3-none-any.whl + sdist
uv tool install ./dist/kin-0.1.0-py3-none-any.whl

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

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). Run uv tool upgrade kin 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.

For development there are also the headless suites (see Testing for the layout), which run with no model and no terminal. From a checkout:

task verify     # the full headless pytest suite (11 suites: harness, settings, banner,
                # app, integration, workflow, search, memory, provider-presets, evals, web —
                # no model, no terminal)
task compile    # syntax-only py_compile across the tree

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.

Setting up a second machine¶

To bring a second machine (kloud, a second laptop, a fresh VM) to full dev parity from an existing checkout:

./scripts/setup-dev.sh     # idempotent — safe to re-run
task verify                # the full headless pytest suite

The script does four things, none of which need sudo:

uv sync — creates .venv, installs all deps from uv.lock.
uv tool install --editable . — installs the kin command on $PATH.
Copies examples/settings.toml.shared-template.toml → ~/.kin/settings.toml (only if not already present). Secrets stay out — enter them via kin → /providers, or set KIN_* env vars per-host.
Appends a one-liner to ~/.bashrc that auto-attaches (or creates) a tmux session named kin on every SSH login.

For the MacOS ↔ kloud workflow — the build-worktree split that keeps deploys from wiping your dev tree, the shared settings baseline, and the cross-machine kloud:* Taskfile verbs — see Multi-machine setup.