Install Nika

Latest engine release: v. 0.124 is the current release line. Work stays focused on maintenance, security and the media capabilities workflows need; native video is planned for 0.125. The 0.123.x line is the previous one. Homebrew, the install script, the release archives and the container image all give you this version. The npm package @ bundles its own engine build, so an npm install never depends on the CLI you installed another way. After installing, nika --version and nika --help are the source of truth for your binary.

Install

macOS and Linux:

brew install supernovae-st/tap/nika
nika --version

Recent Homebrew versions gate third-party taps behind a trust prompt. If the install reports the tap as untrusted, run brew trust supernovae-st/tap once and retry.

curl -LsSf https://nika.sh/install.sh | sh
nika --version

On macOS the script tries Homebrew first when it is available, then falls back to the GitHub release archive; on Linux it always uses the release archive. Without Homebrew the binary lands in ~/.nika/bin/nika, and the script tells you the PATH line to add. Pass --no-brew to skip Homebrew, --version <x.y.z> to pin a release, or --install-dir <dir> to choose the destination. Read the script before you pipe it to sh; it is a small shell file.

Requires Node.js 22 or newer, on macOS (arm64, x64) or Linux with glibc (x64, arm64).

npm install -g @supernovae-st/nika
nika --version

One package gives you the nika command and the TypeScript SDK. The verified engine for your platform arrives as an optional dependency, so keep optional dependencies enabled. Installed per project instead (npm install @supernovae-st/nika), the command is ./node_modules/.bin/nika, or npm exec --no -- nika.

Do not type npx nika outside a project that has the package installed: the unscoped npm name nika belongs to an unrelated package, and npx would download and run it.

The official image, for linux/amd64 and linux/arm64, has nika as its entrypoint:

docker run --rm ghcr.io/supernovae-st/nika:0.124.1 --version
docker run --rm -v "$PWD:/work" -w /work ghcr.io/supernovae-st/nika:0.124.1 check flow.nika
docker run -i --rm ghcr.io/supernovae-st/nika:0.124.1 mcp

The image carries the base shell and coreutils, nothing more; build your own image FROM ghcr.io/supernovae-st/nika:0.124.1 when a workflow runs heavier tools. It has no bubblewrap, so a workflow that declares permits: and runs exec: refuses to start there (NIKA-1710, see Servers and headless Linux) unless you install bubblewrap in your image or set the attested NIKA_SANDBOX=off.

cargo binstall --git https://github.com/supernovae-st/nika nika-cli
nika --version

Fetches the prebuilt release archive (no compilation) and installs the binary as ~/.cargo/bin/nika. The crate is named nika-cli; the binary it installs is nika.

nix run github:supernovae-st/nika/v0.124.1 -- --version
nix profile install github:supernovae-st/nika/v0.124.1

Builds the release tag with the repository’s flake.nix: the first run compiles, and the store caches it. The bare github:supernovae-st/nika reference builds the default branch, which can be ahead of the release.

git clone --branch v0.124.1 https://github.com/supernovae-st/nika.git
cd nika
cargo install --locked --path crates/nika-cli
nika --version

cargo install builds the nika binary into ~/.cargo/bin. Cloning without --branch gives you main, which carries maintenance fixes that are not released yet.

Native Windows binaries are not shipped. On Windows, use WSL2 with the Linux archive.

First run

No account, API key, model download or agent is needed for this step.

Check the binary

nika --version

It prints nika {STATUS.version} ({STATUS.engineSha}) for this release.

Read the mirror

nika welcome

nika welcome prints what this binary contains, what it sees on your machine, and the next line to type. On v that line is ; this page is gated on saying the same thing. Your machine reads the screen line by line.

Write and run a first file, offline

nika compile hello hello.nika
nika check hello.nika
nika run hello.nika
nika trace verify

nika compile hello writes a ready starter file without calling any model, nika check audits it, nika run runs it on mock/echo (a rehearsal model that echoes the prompt back) and nika trace verify checks the record the run left in .nika/traces/.

On a terminal, bare nika (no arguments) opens the terminal Session, where you describe a job in your own words. On a machine with no key, local model or signed-in agent app, it first asks you to choose an intelligence. You can leave with Ctrl+C and come back once one is ready. Piped or redirected, bare nika prints the same mirror as nika welcome.

The loop you will keep using. nika compile writes a starter file, nika check audits it before anything runs, nika run runs it, and nika trace verify confirms the run’s record is intact. All four commands captured from the real CLI on nika 0.121.0, offline; the answer comes from the mock/echo rehearsal model, not a real model.

nika init scaffolds a repository for agents and editors when you want one, not before (what it writes). nika wire <client> adds Nika’s read-only MCP server to one agent client. Installers never edit editor or agent configuration.

Seal your runs

Every run writes a hash-chained record. To also sign it, so that nika trace verify answers SEALED, mint a run-signing key once per machine:

NIKA_KEYCHAIN=off nika key init

This writes the key as files under ~/.nika/keys/ (the private key in mode 0600), where every process reads it, on macOS and on Linux: nika in your terminal, the engines your applications start through the SDK, and nika serve. The SDK’s engines and nika serve never open an OS keychain, so for them the key must be a file. NIKA_KEYCHAIN=off skips only the keychain. Without it, nika key init depends on the platform:

macOS. 0.124.1 opens no keychain, even from a terminal: nika doctor says the keychain is not opened by this ad-hoc build, even for the signed release. A plain nika key init writes the same files, unless the keychain holds a run-key that Nika 0.122 or older stored there. Then it refuses, and the repair it names, nika key align, cannot read or copy that key: it exits with this process does not open the keychain. With the variable, nika key init mints a new key as files, a new signing identity beside the old keychain key.
Linux. Run from a terminal, nika also uses the desktop’s Secret Service, and 0.124.1 cannot tell whether it already holds a run-key. A plain nika key init therefore refuses with run-signing key material already exists, even on a new machine. On a desktop, its --force stores the key in the Secret Service only, where SDK engines and nika serve never look; nika key align, run once from a terminal, copies that key to ~/.nika/keys/.

In CI, set both NIKA_RUN_KEY_FILE and NIKA_RUN_PUB_FILE to two paths: nika key init mints the pair there (or place a pair you already hold), and every run signs with it. Set the same two variables where you verify: nika trace verify then attributes those journals without --key, and a nika serve started with them verifies its jobs’ journals the same way. Without any key, runs still succeed and nika trace verify reports them UNSEALED.

Platforms

Platform	Release asset	Status
macOS Apple silicon	`nika-macos-arm64-<release>.tar.gz`	shipped
macOS Intel	`nika-macos-x64-<release>.tar.gz`	shipped
Linux x86_64	`nika-linux-x64-<release>.tar.gz`	shipped
Linux aarch64	`nika-linux-arm64-<release>.tar.gz`	shipped
Container (linux/amd64, linux/arm64)	`ghcr.io/supernovae-st/nika:<release>`	shipped
Windows	none	not supported: use WSL2
WebAssembly runtime	none	not supported

Each release also publishes supernovae-st-nika-check-wasm-<release>.tgz, a WebAssembly build of the static checker only; it does not run workflows.

Servers and headless Linux

Nika confines every exec: child and external MCP server inside an OS sandbox when the host provides one: Seatbelt on macOS (part of the OS) and bubblewrap on Linux. A minimal server image often lacks bubblewrap; install it once:

# Debian / Ubuntu
apt install bubblewrap

Without a sandbox backend the host reports noop, and the outcome depends on the workflow:

No permits: block. An absent block declares zero authority, so only a file with no effect at all (pure computation, nothing spawned) runs, on a best-effort basis. Any exec: or other effect is refused at admission (NIKA-AUTH-006).
A permits: block and exec: tasks. The run refuses to start (NIKA-1710). A declared boundary the host cannot enforce would be a broken promise, so the engine fails closed instead of running unconfined.

The posture is one setting, read once at launch:

NIKA_SANDBOX=auto     # default · the behavior above
NIKA_SANDBOX=require  # refuse ANY unconfined start, permits or not
NIKA_SANDBOX=off      # proceed unconfined · attested

off is a waiver, not a silent escape: the run’s journal records sandbox_policy and sandbox_waived on its opening frame, so a sealed trace shows you chose it. An unknown value refuses to start (NIKA-1711). nika doctor shows the backend in its sandbox row, and nika explain NIKA-1710 teaches the refusal with the fix for each OS.

Verify a download

Every release publishes its archives with SHA256SUMS and two kinds of build provenance. Download one archive and the checksum file:

gh release download v0.124.1 --repo supernovae-st/nika \
  -p 'nika-macos-arm64-0.124.1.tar.gz' -p SHA256SUMS

Then check what you hold, in up to three independent ways:

# 1 · checksum: the bytes you hold are the bytes CI hashed
shasum -a 256 -c SHA256SUMS --ignore-missing     # Linux: sha256sum -c SHA256SUMS --ignore-missing

# 2 · GitHub build attestation for this exact archive
gh attestation verify nika-macos-arm64-0.124.1.tar.gz --repo supernovae-st/nika

# 3 · SLSA provenance, verifiable offline
gh release download v0.124.1 --repo supernovae-st/nika -p multiple.intoto.jsonl
slsa-verifier verify-artifact nika-macos-arm64-0.124.1.tar.gz \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/supernovae-st/nika --source-tag v0.124.1

Replace macos-arm64 with macos-x64, linux-x64 or linux-arm64 for your platform. --ignore-missing checks only the archives you downloaded.

A real answer, later

The first run is a rehearsal. When you want a real answer, choose one path:

A model on this machine. nika model pull and nika model serve, or a local server such as Ollama. See Local models.
A provider key. Export the provider’s variable in your shell; the providers catalog names each one.
An agent app you already use. A signed-in agent CLI such as Claude Code or Codex can serve a run through --access. See Harness access.

nika doctor reports which of these your machine can use, by presence only: it never prints a key’s value.

What Nika writes on your machine

nika, one binary. No daemon, no background service, no telemetry.

~/.nika/, created when you first need it:

Path	Written by	Holds
`~/.nika/inference-choice.json`	bare `nika`, `nika welcome`	the intelligence recommendation shown in the mirror
`~/.nika/session-intelligence.json`	the Session	your intelligence choice
`~/.nika/sessions/`	the Session	conversation history, per project
`~/.nika/keys/`	`nika key init`, `nika key align` on Linux	run-signing keys (private key mode `0600`)
`~/.nika/models/`	`nika model pull`	downloaded model files
`~/.nika/approval-claims/`	runs with a human gate	which approvals were already used
`~/.nika/bin/nika`	the install script, without Homebrew	the binary

In a project directory: .nika/traces/ (run records) and other .nika/ state appear when you run workflows there; nika init and nika wire write only the files they list.

Shell completions

The binary generates its own completions, always in step with the verbs your version ships:

zsh
bash
fish

mkdir -p ~/.zsh/completions
nika completions zsh > ~/.zsh/completions/_nika
# once, in ~/.zshrc (before compinit):
# fpath=(~/.zsh/completions $fpath)
exec zsh

mkdir -p ~/.local/share/bash-completion/completions
nika completions bash > ~/.local/share/bash-completion/completions/nika
exec bash

nika completions fish > ~/.config/fish/completions/nika.fish

elvish and powershell are available too. Run the same command again after an upgrade to pick up new verbs.

Uninstall

Remove the binary the way you installed it:

brew uninstall nika                          # Homebrew
rm ~/.nika/bin/nika                          # install script without Homebrew
npm uninstall -g @supernovae-st/nika         # npm
rm ~/.cargo/bin/nika                         # cargo binstall or cargo install
nix profile remove nika                      # Nix (see `nix profile list` for the name)
docker image rm ghcr.io/supernovae-st/nika:0.124.1   # container

Then, if you want no trace left, remove Nika’s state:

rm -rf ~/.nika

~/.nika/keys/ holds your run-signing key. Without it you can no longer seal new runs under the same key, and a verifier needs the public key to check old seals. Keep a copy if you need one. A key that Nika 0.122 or older minted in a macOS terminal, or that nika key init --force stored in a Linux desktop’s Secret Service, lives there instead, under the nika service.

The terminal Session

Describe a job in your own words; review the file before it is saved.

First workflow

Write one .nika file by hand, check it, run it.

Your machine

Read the mirror and the diagnosis this binary prints.

Editor setup

Schema validation and the nika lsp language server.

The Nika ecosystem

Documentation

Guides, reference contracts and working examples.

Language spec

the nine-key envelope, Apache-2.0. The contract these docs explain.

Engine source

Rust, AGPL-3.0-or-later. Every commit public.

TypeScript SDK

Use one typed lifecycle locally or against authenticated nika serve HTTP.

Editor extension

The editor extension, frozen at 0.120 and not qualified with 0.124: use nika lsp and the JSON Schema.

Homebrew tap

brew install supernovae-st/tap/nika for the latest tagged CLI release.

SuperNovae

The Paris studio crafting Nika. 🦋

Overview

Getting started

Author workflows

Models and media

Operate and troubleshoot

Agents & integrations

Concepts

Install Nika

Install

First run

Seal your runs

Platforms

Servers and headless Linux

Verify a download

A real answer, later

What Nika writes on your machine

Shell completions

Uninstall

Next

The terminal Session

First workflow

Your machine

Editor setup

The Nika ecosystem

Documentation

Language spec

Engine source

TypeScript SDK

Editor extension

Homebrew tap

SuperNovae

​Install

​First run

​Seal your runs

​Platforms

​Servers and headless Linux

​Verify a download

​A real answer, later

​What Nika writes on your machine

​Shell completions

​Uninstall

​Next

The terminal Session

First workflow

Your machine

Editor setup

​The Nika ecosystem

Documentation

Language spec

Engine source

TypeScript SDK

Editor extension

Homebrew tap

SuperNovae

Install

First run

Seal your runs

Platforms

Servers and headless Linux

Verify a download

A real answer, later

What Nika writes on your machine

Shell completions

Uninstall

Next

The Nika ecosystem