Install¶

kata is a single Go binary. It has no runtime service dependency beyond the daemon it starts itself, and it stores data locally in SQLite.

Requirements¶

The release installers below do not require Go. Install Go 1.27 or later from https://go.dev/dl/ only when using go install or building from a clone.

GitHub release binaries are available starting with v0.5.0. Since v0.14.0, kata publishes stable releases that preserve backward compatibility across upgrades.

The recommended path on macOS is Homebrew Core:

brew install kata

Homebrew owns this binary. Check Kata's release feed with kata update --check, and install packaged updates with:

brew upgrade kata

The formula may trail a newly published GitHub release. On Linux, or to install an ordinary release archive on macOS instead:

curl -fsSL https://katatracker.com/install.sh | bash

Linux and WSL 2 users who already use Homebrew can install from Core instead:

brew install kata

On Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://katatracker.com/install.ps1 | iex"

The installers detect your OS and CPU architecture and download the latest archive from GitHub releases. They verify the downloaded archive against SHA256SUMS before installing it. For v0.14.x and newer versions, they also ask the extracted binary to validate its embedded Web UI before replacement. The installer remains able to install canonical older releases that predate that embedded-asset check. The shell installer shows a download progress line when run in a terminal. It aborts a transfer that stalls for 30 seconds and tries each download up to three times. If every attempt fails, it suggests running the installer again, installing with Homebrew, or downloading the release manually. The shell installer places kata in /usr/local/bin or ~/.local/bin. The PowerShell installer places kata.exe in %USERPROFILE%\.kata\bin by default and adds that directory to the user Path. Review the installers at https://katatracker.com/install.sh and https://katatracker.com/install.ps1 before running them if you prefer.

Linux .deb and .rpm packages are also published for amd64 and arm64. Download the package for your distribution from GitHub releases, then install it with your system package tool. Upgrade those installations with the same package manager; Kata will not replace a package-owned binary itself.

After installing a release build, check for newer releases:

kata update --check

For an ordinary release archive or installer-based installation, install an available update from GitHub release assets:

kata update

kata update verifies the downloaded archive against SHA256SUMS before replacing the installed binary. After a successful install, it asks a running local daemon to restart itself through the new binary. The daemon restarts with its own startup options and environment, so --listen, --insecure-readonly, authentication tokens, and the auto-start idle timeout carry over without the updater knowing them. A stopped daemon stays stopped. Reopen kata ui if the daemon used an ephemeral port, because the replacement binds a new one.

If the daemon does not come back, or it does not support automatic restart, the command reports that the binary was installed and returns an error. Resolve any reported startup problem, then run kata daemon restart with the daemon's original startup options.

The daemon sends limited anonymous usage reports by default. Set KATA_TELEMETRY_ENABLED=0 in the daemon's environment to turn them off; see Telemetry for what is collected.

Package-managed installations keep kata update --check, but install-capable update forms direct you back to the owning package manager. Packagers can read the complete packaging contract. Installing with go install remains supported, and building from a clone is still useful for development builds.

Upgrading to 0.19.0¶

Upgrade the daemon as well as the CLI and MCP server. Kata 0.19.0 includes daemon API 0.28.0; release and API versions are separate. Timed claims require API 0.22.0, move --dry previews 0.23.0, close session references 0.26.0, paginated lists 0.27.0, and comment replies 0.28.0. See the API version history.

Update scripts that call renamed commands and flags. The old spellings are no longer accepted:

Reinstall user hooks with kata agent-hook install. For workspace hooks, re-run kata agent-hook install <harness> --local or the kata init hook option that installed them. Reinstalling replaces hooks that still call the plural command. Hook installation now enables available attention hooks by default; pass --contract-only to keep contract-only setup. See the agent-hook reference.

For federation, upgrade hubs before their spokes. A hub rejects pushes from a spoke with a newer storage schema until the hub is upgraded; the spoke retries automatically. Project relays need 0.19.0 on every participating daemon. See rolling upgrades. External-agent enrollment no longer sends the local KATA_AUTH_TOKEN to the hub; pass --hub-token-env <env-name> or configure a daemon catalog entry that matches --hub-url.

PostgreSQL operators should stop the daemon and run kata storage postgres migrate with schema-owner credentials before starting the new release. Follow the upgrade ceremony.

Go programs that embed Kata and serve the browser application must now pass webui.NewEmbeddedHandler() in kata.Config.WebHandler. See Serve the browser application.

For feature details, see the 0.19.0 release notes. If upgrading from before 0.18.0, also follow the guidance below.

Upgrading to 0.18.0¶

Upgrade the daemon as well as the CLI and MCP server. Kata 0.18.0 includes daemon API 0.21.0; release and API versions are separate. Status-filtered search requires API 0.20.0, and kata list --sort oldest requires 0.21.0. See the API version history.

Upgrade all participating daemons before relying on federation to preserve teammate attribution. To use issue-scoped worker credentials, enable token identity mode on the authoritative daemon. Spoke replicas cannot create these credentials.

When updating from a release before 0.18.0, run kata daemon restart with the original startup options after installing the new binary. The older updater does not restart the daemon automatically. For later updates, the new kata update can restart a running local daemon; follow any manual-restart instructions it reports. Reopen kata ui if the browser port changed. Package-managed installations still use their package manager to update the binary.

For feature details, see the 0.18.0 release notes. If upgrading from before 0.17.0, also follow the guidance below.

Upgrading to 0.17.0¶

Upgrade the remote daemon alongside the CLI. Simple remote writes now select the project in the write request, and older daemons reject those selectors. See remote command behavior.

Custom API clients must use case-sensitive request field names, send [] instead of null for arrays, and accept empty response collections as [] or {}. See the HTTP API contract.

Keep a backup before upgrading. The SQLite fix preserves moved-issue history during future upgrades; it cannot restore history lost during an earlier upgrade.

Install with go install¶

go install go.kenn.io/kata/cmd/kata@latest

This module-source install includes the CLI, daemon, and TUI, but Go does not run the browser asset toolchain. To use kata ui, install a release binary or build from a clone with make install so the compiled browser bundle is embedded.

Go writes the binary to $(go env GOBIN) when set, otherwise to $(go env GOPATH)/bin. Common defaults are ~/go/bin on Unix and %USERPROFILE%\go\bin on Windows. Put that directory on PATH.

Check the install:

kata version   # or kata --version
kata --help

Install from a release manually¶

Download the archive for your platform from the GitHub releases page, extract it, and place the kata binary on PATH.

Build from a clone¶

On macOS or Linux:

git clone https://github.com/kenn-io/kata.git
cd kata
make install

make install honors GOBIN and defaults to ~/.local/bin:

make install GOBIN=/usr/local/bin

On Windows, PowerShell or cmd.exe:

git clone https://github.com/kenn-io/kata.git
cd kata
go build -o kata.exe ./cmd/kata

Move kata.exe to a directory on PATH.

Documentation tooling¶

This site is built with Zensical. Install the docs toolchain into a local virtual environment:

make docs-install

Build or preview the site:

make docs-build
make docs-serve

make docs-check runs the repository's docs structure check and then runs a strict Zensical build when Zensical is installed.