Installation

Install the Ayni CLI first. Managed environments are provisioned separately for each repository from its committed environment lock.

Install a published release

The installer detects your operating system and architecture, downloads the matching release archive and SHA256SUMS, requires sha256sum or shasum to verify the archive, validates the archive layout, and installs ayni into ~/.local/bin.

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/ayni-oss/ayni/main/install.sh | sh

Review the installer before running it if that is your normal security practice. Running the downloaded script directly also enables its optional interactive install-directory and PATH prompts:

curl --proto '=https' --tlsv1.2 -fsSLO \
  https://raw.githubusercontent.com/ayni-oss/ayni/main/install.sh
less install.sh
sh install.sh

The installer needs curl or wget, tar, and install. Add ~/.local/bin to PATH if it is not already present:

export PATH="$HOME/.local/bin:$PATH"

Pin a version or install location

Set VERSION to a release tag to make the installation reproducible:

VERSION=ayni-v0.10.0 sh install.sh

Set INSTALL_DIR to choose another binary directory:

INSTALL_DIR="$HOME/bin" sh install.sh

Both variables also work with the piped installer:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/ayni-oss/ayni/main/install.sh |
  VERSION=ayni-v0.10.0 INSTALL_DIR="$HOME/bin" sh

Supported release targets

Platform	Release target
macOS on Apple silicon	aarch64-apple-darwin
macOS on Intel	x86_64-apple-darwin
Linux GNU on ARM64	aarch64-unknown-linux-gnu
Linux GNU on x86-64	x86_64-unknown-linux-gnu

Windows and Linux distributions without glibc do not currently have prebuilt release archives. Managed execution is currently documented and released for the macOS and Linux targets above.

Download a release manually

Release archives and checksums are published on the GitHub Releases page. A complete release contains one archive for each of the four supported targets plus SHA256SUMS; release automation fails if that public inventory or any installer smoke test is incomplete. Archive names include the complete release tag and follow this pattern:

ayni-<release-tag>-<target>.tar.gz

For example, release tag ayni-v0.10.0 produces archive names beginning with ayni-ayni-v0.10.0-.

For example, select a version and target, then download both the archive and checksum manifest:

VERSION=ayni-v0.10.0
TARGET=aarch64-apple-darwin
ARCHIVE="ayni-${VERSION}-${TARGET}.tar.gz"
BASE_URL="https://github.com/ayni-oss/ayni/releases/download/${VERSION}"

curl --proto '=https' --tlsv1.2 -fsSLO "${BASE_URL}/${ARCHIVE}"
curl --proto '=https' --tlsv1.2 -fsSLO "${BASE_URL}/SHA256SUMS"

Verify the download before extracting it. On macOS:

EXPECTED="$(awk -v name="$ARCHIVE" '{ file=$2; sub(/^.*\//, "", file); if (file==name) { print $1; exit } }' SHA256SUMS)"
ACTUAL="$(shasum -a 256 "$ARCHIVE" | awk '{ print $1 }')"
test -n "$EXPECTED" && test "$EXPECTED" = "$ACTUAL"

On Linux, replace shasum -a 256 with sha256sum. Then extract and install:

tar -xzf "$ARCHIVE"
mkdir -p "$HOME/.local/bin"
install -m 0755 "ayni-${VERSION}-${TARGET}/ayni" "$HOME/.local/bin/ayni"

Build from source

Building requires Git and the Rust toolchain version declared by the repository:

git clone https://github.com/ayni-oss/ayni.git
cd ayni
cargo install --locked --path cli

Cargo installs the binary into ~/.cargo/bin by default.

Verify the installation

ayni --version
ayni --help

Installing the CLI does not install every language tool used by a repository. For reproducible execution, Ayni derives and builds an image after the repository has an .ayni.toml and .ayni.lock.

Environment-image prerequisites

To build an image:

• Provide Docker CLI, Buildx, and an engine supporting build, image inspection, and container execution.
• Install Mise when resolving a new lock with ayni env lock.
• Commit the native project metadata and dependency locks required by each language adapter.

Building an existing lock does not require host Mise or project toolchains. For Kubernetes or CI, use the versioned ghcr.io/ayni-oss/ayni-builder:<version> factory with an external engine. It builds a separate repository image; agents and quality commands run in that resulting image. For an explicit builder selection, pin its immutable digest:

ayni env build --executor-image 'ghcr.io/ayni-oss/ayni-builder:<version>@sha256:<digest>'

See Managed environments for the complete lifecycle and per-language readiness requirements.

Upgrade

Run the installer again to replace the existing binary with the latest release:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/ayni-oss/ayni/main/install.sh | sh

Use VERSION=<release-tag> to upgrade to a specific version or roll back. After changing Ayni or repository runtime inputs, run ayni env doctor; regenerate and commit .ayni.lock when it reports stale state.

Uninstall

Remove the installed binary from the directory you selected:

rm "$HOME/.local/bin/ayni"

If you added a dedicated Ayni PATH entry to a shell startup file, remove that line as well. Repository files such as .ayni.toml, .ayni.lock, .ayni/, and OCI images are not removed automatically.

Next: follow the Quickstart to preview a policy and produce managed evidence.