Install

One-command install (macOS · Linux)

curl -fsSL https://ikenga.dev/install.sh | sh

The script detects your OS and architecture, downloads the matching artifact from the latest GitHub Release, and installs it:

macOS — mounts the signed .dmg and copies Ikenga.app into /Applications, clearing the Gatekeeper quarantine flag on the copy.
Linux — defaults to the system-wide .deb (~60 MB) when dpkg is present, printing the single sudo apt-get install line to paste; otherwise it installs the no-sudo AppImage (~140 MB) to ~/.local/bin/ikenga and makes it executable. Force either with IKENGA_FORMAT=deb or IKENGA_FORMAT=appimage. Both download from GitHub’s release CDN, which can run slowly — give the transfer a minute or two before assuming it stalled.

macOS — Apple Silicon and Intel

The installer picks the right artifact for your chip. On Apple Silicon (arm64) it installs the native build where one exists; otherwise it points you at the issue tracker rather than installing the wrong binary.

Linux — arm64

Download and inspect (the no-`curl | sh` path)

If you’d rather not pipe a script straight into your shell, you don’t have to.

Open the latest release and download the artifact for your platform directly — .dmg (macOS), .AppImage or .deb (Linux), .exe (Windows).

To read the installer before running it:

curl -fsSL https://ikenga.dev/install.sh -o install.sh
less install.sh        # read it
sh install.sh          # then run it

Verify the download against the checksums published on the release page before you run anything.

Windows

winget install Ikenga.Shell

Or download the .exe installer directly from the latest release.

Environment overrides

The install script honours three environment variables:

Variable	Default	Purpose
`IKENGA_VERSION`	`latest`	Pin a specific release tag (e.g. `v0.0.4`).
`IKENGA_FORMAT`	`deb` if `dpkg` present, else `appimage`	Linux installer format. `deb` is the smaller (~60 MB) system-wide install (needs sudo); `appimage` is the larger (~140 MB) no-sudo portable build.
`IKENGA_INSTALL_DIR`	`~/.local/bin`	Linux portable (AppImage) install location. Ignored when `IKENGA_FORMAT=deb`.
`IKENGA_REPO`	`Royalti-io/ikenga`	Source repository.
`IKENGA_BUN_PATH`	(none)	Runtime override. Absolute path to a `bun` binary the shell should use in place of its own fetched copy. See Offline / air-gapped install below.

Example — pin a version and install to a different directory:

curl -fsSL https://ikenga.dev/install.sh | \
  IKENGA_VERSION=v0.0.4 IKENGA_INSTALL_DIR=$HOME/opt/bin sh

Offline / air-gapped install

Ikenga’s built-in pkg system uses Bun as its JavaScript runtime. On a normal first launch the shell fetches the pinned Bun release in the background — a small status chip in the shell chrome shows download progress — and the rest of the app is fully usable while the transfer completes. Nothing blocks startup.

If you are on a restricted network, or simply prefer to supply your own binary, three escape hatches are available.

Option 1 — use a system Bun

Install Bun yourself (see bun.sh/docs/installation) and make the bun binary available on your $PATH. At startup the shell detects it, checks the version, and uses it if the version meets or exceeds the pinned minimum (currently 1.3.14). No download occurs.

# Verify Bun is on PATH and meets the minimum version
bun --version   # must be >= 1.3.14

Option 2 — drop a binary in the data directory

Copy a Bun binary directly into the location the shell checks:

Platform	Path
macOS	`~/Library/Application Support/app.ikenga/bun/<target>/bun`
Linux	`~/.local/share/app.ikenga/bun/<target>/bun`
Windows	`%APPDATA%\app.ikenga\bun\<target>\bun.exe`

Where <target> matches your platform:

Platform	`<target>`
macOS Apple Silicon	`darwin-aarch64`
macOS Intel	`darwin-x64`
Linux x64	`linux-x64`
Linux arm64	`linux-aarch64`
Windows x64	`windows-x64`

The shell validates the file’s SHA-256 against its pinned checksum. If the checksum does not match, the binary is rejected and a background fetch is attempted instead.

Option 3 — `IKENGA_BUN_PATH` environment variable

Set IKENGA_BUN_PATH to the absolute path of any bun binary before launching the shell:

IKENGA_BUN_PATH=/opt/bun/bin/bun ikenga

A binary provided this way is trusted without checksum verification — you are asserting that you control the binary. It takes precedence over all other resolution paths. The variable is not read by the install script; set it in your shell profile (.bashrc, .zshrc, etc.) or via a .env file if your deployment platform supports one.

First launch

Open Ikenga. The first run is consecration — the short ritual that brings a new workspace to life. You’ll:

Set up your engine (your Chi). Ikenga is engine-optional — the shell boots and runs without one — but you’ll want at least one to chat. Claude Code is fully wired; Codex and Gemini are pluggable adapters. Each engine needs its CLI on your $PATH and its own auth (for example, claude login for Claude Code). The onboarding wizard tells you exactly which key or command each engine wants.
Land in your Obi — the home view, with the split panes (terminal · chat · file viewer) side by side.
Commission a project when you’re ready to start real work.

From here:

Add capabilities with the ikenga CLI — ikenga list, ikenga add <pkg>. See Pkgs →.
Build your own pkg — start with the Build your first pkg tutorial.
Drive a running shell from the terminal with the iyke CLI and mcp-iyke.