Installation & updates

Kuru ships native executables for macOS, Linux and Windows, with the verified full-Dolt engine and its licenses included. Install with mise or your platform's bootstrap, then run kuru.

Install with mise

With mise installed and activated:

mise use -g github:replygirl/kuru
kuru --version

This installs the native executable and selects it globally. Omit -g for a project-local selection. To install and activate an exact release, replace VERSION in the examples below with a full major.minor.patch version from releases that includes your platform's archive:

mise use -g github:replygirl/kuru@VERSION

Mise applies a release-age cooldown when resolving latest; a full major.minor.patch pin also lets you select a newly published release. mise install github:replygirl/kuru@VERSION downloads the version without selecting it. Use mise exec github:replygirl/kuru@VERSION -- kuru to run that version explicitly.

Before publication, each release's exact Windows package is tested through native mise on Windows, including its bundled Dolt runtime and reopening a saved offline conversation from empty application and engine caches. Installation still needs no compiler or separate database.

Ordinary Kuru commands start or attach to a private per-project memory service from the installed executable. It is not registered as an operating-system service, requires no separately installed database daemon, and exits once clients and accepted work have drained.

Install with the shell bootstrap

On macOS or Linux:

curl -fsSL https://raw.githubusercontent.com/replygirl/kuru/main/packages/kuru-delivery/support/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
kuru --version

The bootstrap installs the latest release into ~/.local/bin. Add that directory to your shell configuration's PATH for future terminals. Installation uses Bash 3.2 or newer, curl, tar, gzip, and either sha256sum or shasum, plus standard system utilities; no Rust toolchain is required.

To choose a version and destination:

curl -fsSL https://raw.githubusercontent.com/replygirl/kuru/main/packages/kuru-delivery/support/install.sh -o /tmp/kuru-install.sh
bash /tmp/kuru-install.sh --version VERSION --install-dir "$HOME/.local/bin"

KURU_INSTALL_DIR also sets the destination; the CLI option takes precedence. The installer resolves latest once to a specific version, verifies the archive checksum, and extracts only the executable into staging before replacing it atomically. It does not run the candidate during installation. It rejects symlink or directory destinations. Failures and handled interruptions before replacement preserve the existing executable.

Try a conversation without credentials:

kuru --provider demo

Continue with your first conversation or authentication for live inference.

Install with PowerShell

In stock Windows PowerShell 5.1:

irm https://raw.githubusercontent.com/replygirl/kuru/main/packages/kuru-delivery/support/install.ps1 | iex
$env:PATH = "$env:LOCALAPPDATA\Programs\kuru\bin;$env:PATH"
kuru --version

The default destination is $env:LOCALAPPDATA\Programs\kuru\bin. Add it to your user PATH for future terminals. Installation uses stock PowerShell/.NET facilities and needs no separately installed compiler, Dolt server or MSVC redistributable. It loads PowerShell's own Management and Utility modules directly from $PSHOME, so a fresh Windows profile does not search every installed module before the first stage.

To select a release and destination, download the script first:

irm https://raw.githubusercontent.com/replygirl/kuru/main/packages/kuru-delivery/support/install.ps1 -OutFile "$env:TEMP\kuru-install.ps1"
& "$env:TEMP\kuru-install.ps1" -Version VERSION -InstallDir C:\Tools\kuru\bin

Replace VERSION with a version from releases. -InstallDir overrides KURU_INSTALL_DIR; use an ordinary directory on a local drive. -ReleaseBase overrides KURU_RELEASE_BASE and accepts an HTTPS version directory or a local directory containing the Windows ZIP and SHA256SUMS. A custom base requires -Version.

The bootstrap freezes latest to an explicit version, verifies the ZIP checksum and its exact three regular members, then publishes kuru.exe from private staging. It refuses reparse points, extra hardlinks and ambiguous names. It does not execute the downloaded candidate for validation. A private .kuru-update directory beside the executable coordinates installation and recovery.

The script selects the Windows target from the machine the operating system reports, never from PROCESSOR_ARCHITECTURE or PROCESSOR_ARCHITEW6432, so it installs x86_64-pc-windows-msvc on x64 Windows and aarch64-pc-windows-msvc on Windows 11 on Arm. Run it from 64-bit stock Windows PowerShell 5.1. An explicit -Target must equal that native target: requesting the x64 build on Arm, or the Arm build on x64, fails with Requested target ... does not match the native machine target ..., naming the native target, before anything is downloaded. The downloaded kuru.exe must carry the native PE machine. A release that has no archive for the native target fails with Release vVERSION publishes no TARGET archive; nothing was installed.; releases before Windows on Arm support publish only the x64 ZIP.

Supported platforms

System	Architecture	Target
macOS	Apple Silicon	aarch64-apple-darwin
Linux	ARM64	aarch64-unknown-linux-gnu
Linux	x86-64	x86_64-unknown-linux-gnu
Windows 10 version 1809 or newer	x86-64	x86_64-pc-windows-msvc
Windows 11 or newer	ARM64	aarch64-pc-windows-msvc

Linux archives are built on Ubuntu 24.04 and need a compatible glibc. Linux support uses GNU targets; musl targets are not supported. The shell bootstrap's --target overrides host detection for supported tar targets. PowerShell uses the ZIP for the native Windows machine and accepts only that target as an explicit -Target. Windows on Arm requires Windows 11 because the installer's stock .NET Framework 4.8.1 runs natively on Arm64 only there; x64 keeps the Windows 10 version 1809 floor. Windows 10 on Arm is not supported.

Intel Macs (x86_64-apple-darwin) are not supported after v0.9.0, and the current shell bootstrap refuses them before downloading anything. On Apple Silicon, a Rosetta-translated shell reports x86_64; the bootstrap detects the translation and selects aarch64-apple-darwin instead. To install v0.9.0 on an Intel Mac, use that tag's own bootstrap with an explicit version:

curl -fsSL https://raw.githubusercontent.com/replygirl/kuru/v0.9.0/packages/kuru-delivery/support/install.sh | bash -s -- --version 0.9.0

Release archives and mirrors

Release archives use kuru-VERSION-TARGET.tar.gz for macOS/Linux and kuru-VERSION-TARGET.zip for both Windows targets (x86_64-pc-windows-msvc and aarch64-pc-windows-msvc), alongside SHA256SUMS. Archives contain the executable, LICENSE and README.md. To use a mirror, pass its HTTPS version directory and an explicit version:

Archive size depends on release and target. For example, the v0.9.0 release assets published on 2026-09-25 ranged from about 45 to 49 MiB compressed. That is a dated example of complete release-archive downloads, not the installed executable or the expanded engine cache; use the current release assets for the selected target.

bash /tmp/kuru-install.sh --version VERSION \
  --release-base https://github.com/replygirl/kuru/releases/download/vVERSION

For offline installation, place the matching archive and SHA256SUMS in one local directory:

bash /tmp/kuru-install.sh --version VERSION --release-base /path/to/release-files

KURU_RELEASE_BASE sets the same option; the CLI overrides it. A custom base requires --version and is used directly. Remote downloads and redirects require HTTPS. Checksums are verified before extraction, and downloads and expanded output have size limits. Checksums detect corruption; choose a release source you trust.

Build from source

Install mise, a C compiler for the legacy SQLite importer, and standard platform build tools, then:

git clone https://github.com/replygirl/kuru.git
cd kuru
bash scripts/install.sh --source

On Windows, install Visual Studio C++ Build Tools and the Windows SDK, then run this from the checkout:

& .\scripts\install.ps1 -Source

The source installer prepares the pinned Rust toolchain and verified engine archive through package-owned mise tasks. It installs the complete executable into ~/.local/bin on macOS/Linux or $env:LOCALAPPDATA\Programs\kuru\bin on Windows. Add that directory to your PATH if needed.

To choose another destination:

KURU_INSTALL_DIR="$HOME/.local/bin" bash scripts/install.sh --source

On Windows, use & .\scripts\install.ps1 -Source -InstallDir C:\Tools\kuru\bin. Release-selection options do not apply to source builds. The Windows task builds the explicit MSVC target with a static C runtime. Like the release installer, the checkout entrypoint loads PowerShell's own Management and Utility modules directly from $PSHOME before its first command, so a fresh Windows profile does not search every installed module.

The source installer builds the locked release profile for the current host and replaces the executable atomically. It refuses a symlink or directory at the destination and uses the current checkout revision. From a configured maintainer checkout, mise run install performs the same source installation. Source installation prepares only its required tooling; it does not require the full maintainer setup.

Prepare engine build inputs

Ordinary mise build tasks prepare the engine archive automatically. To import a pinned archive for an offline build:

mise run //packages/kuru-memory:bundle:prepare -- \
  --target x86_64-unknown-linux-gnu \
  --archive /absolute/path/to/dolt-linux-amd64.tar.gz --offline

Select your target and its matching archive from packages/kuru-memory/support/dolt-assets.json. Imported bytes receive the same size and checksum verification as downloads. KURU_DOLT_BUNDLE_DIR selects an absolute build-input cache for preparation and compilation; KURU_DOLT_BUNDLE_OFFLINE=true prevents preparation from downloading missing archives. The Rust toolchain and Cargo dependencies also need to be available before building offline.

Cargo embeds verified local input for its actual target and never downloads an engine itself. Prepare that input before a direct Cargo build. See the developer build-input guide for explicit target builds and mirrors. Installed Kuru extracts its bundled engine locally, so a first offline demo conversation needs no build cache or compiler.

Updating

For a mise-managed binary selected as latest:

mise upgrade github:replygirl/kuru

For an exact pin, select the new version with mise use -g github:replygirl/kuru@VERSION. Update mise-managed binaries through mise.

On Unix, kuru update refuses mise- and Homebrew-owned installations in both release and source modes before downloads or builds. It detects ownership from the resolved installation path, including aliases, and names the owning manager's command: mise upgrade github:replygirl/kuru or brew upgrade kuru. Homebrew distribution itself remains deferred.

For a direct installation, rerun your platform's bootstrap to install latest, or select an explicit release with Kuru's native updater:

kuru update --version VERSION --release-base https://github.com/replygirl/kuru/releases/download/vVERSION

Replace VERSION in both places with the desired version. This command also works in PowerShell; a local release directory also works. The updater validates the archive in Rust and replaces the running executable. It keeps the running executable's target, so an x64 kuru.exe running under emulation on Windows on Arm keeps updating to x64 builds. No compiler or interpreter is required. Updates are explicit; Kuru does not install background updates.

On macOS and Linux, the native updater records checked replacement evidence beside the installation before preparing either image. An ordinary later Kuru invocation automatically reconciles a pending update before loading configuration or opening memory; recovery notices and retained-evidence refusals go to stderr. A confirmed replacement finishes forward and removes its displaced copy. Recovery never opens memory or rolls back a possibly published new version. Unknown or changed files remain untouched. A settled update leaves no backup executable.

If a pending update still has an installed Kuru, run that executable once before rerunning the shell installer. If the installed name is missing, the installer preserves the pending directory separately and installs only your requested release; it does not execute or restore the retained backup. The shell installers check again before replacement but do not share the native transaction lock. An already-running Linux Kuru keeps self-launching its own mapped build for memory services after its installation pathname is replaced.

On Windows, a verified copy of the current running executable performs publication and records its result before success is reported. It waits for the original process to exit before deleting the displaced image. The trusted helper stays in a private cache for recovery. Close other old Kuru instances if cleanup remains pending, then rerun the normal PowerShell installer. It reconciles the receipt even if an interrupted update left kuru.exe absent, and refuses an unknown occupant at that path. -Recover performs recovery alone.

For a source installation, select the desired revision and install again, or run:

kuru update --source /path/to/kuru

The native Unix source updater builds through the selected checkout's package-owned mise task and copies its verified output without executing it or modifying Cargo hardlinks. Ctrl-C waits for that same owned build and its children, or an already started installation transaction, to settle before exit. The source first-install script still runs its installed --version smoke check after publication.

If the first launch fails

Symptom	Next step
kuru is not found	Activate mise or add the installation directory to PATH.
A new release is missing from mise's latest selection	Select its full version with github:replygirl/kuru@VERSION.
ChatGPT is not authenticated	Run kuru login, or use kuru login --device; see authentication.
A release cannot be downloaded	Check the version and release directory against the available release assets.
State directory is inside the workspace	Set --data-dir to a private directory outside the project.