Installation

Revka ships as a single Rust binary (revka) that runs everywhere from a Raspberry Pi to a production cloud cluster. This page covers every supported way to get that binary onto your machine: the one-line bootstrap, package managers (Homebrew, Scoop), the Windows setup script, pre-built release binaries, source builds, and Docker.

If you just want the fastest path, use the one-click bootstrap. After installing, run the onboarding wizard and then head to the Quickstart.

Pick your path

Most users want Homebrew (macOS/Linux), Scoop or setup.bat (Windows), or the install.sh one-liner (any Unix). Reach for a source build only when you need compile-time features, and Docker when you want an isolated, reproducible runtime.

Resource requirements

Pre-built binaries have negligible requirements — they just download and run. Source builds are heavier:

Resource	Minimum for source build
RAM	2 GB (plus swap)
Free disk	6 GB
Rust toolchain	1.87+

The bootstrap installer enforces these with a preflight check before compiling. You can tune the thresholds with REVKA_BOOTSTRAP_MIN_RAM_MB (default 2048) and REVKA_BOOTSTRAP_MIN_DISK_MB (default 6144). On constrained devices such as a Raspberry Pi, prefer --prefer-prebuilt (see below) to skip compilation entirely.

One-click bootstrap

install.sh is a POSIX shell installer that automates the whole flow: it checks RAM/disk, optionally installs Rust and the OS compiler toolchain, builds from source or downloads a verified pre-built binary, runs revka onboard, and can start the daemon. It has both guided (interactive) and fully non-interactive modes, plus a Docker-first mode.

Remote one-liner

curl -fsSL https://raw.githubusercontent.com/KumihoIO/Revka/main/install.sh | bash

If you run this outside a repository checkout, the script clones a temporary workspace, builds, installs, and cleans up after itself.

Clone + local script

git clone https://github.com/KumihoIO/Revka.git
cd revka
./install.sh

For high-security environments, prefer this path so you can review the script before running it.

Fresh machine

./install.sh --install-system-deps --install-rust

Installs the compiler toolchain (may require sudo) and Rust via rustup before building.

By default the script is app-only and assumes an existing Rust toolchain. Its default actions are:

cargo build --release --locked
cargo install --path . --force --locked

Pre-built vs source build

The bootstrap can either compile from source (full control over Cargo features) or pull a verified pre-built binary from GitHub Releases (no compiler needed, much faster).

./install.sh --prefer-prebuilt      # download binary first, fall back to source
./install.sh --prebuilt-only        # binary only — fail if no matching asset
./install.sh --force-source-build   # never use a pre-built binary

Note

Source builds let you select compile-time integrations (Matrix, hardware, OpenTelemetry, and more). Pre-built binaries are built with a fixed feature set. See Cargo feature flags for the full list.

Non-interactive setup

Seed the provider and API key so onboarding runs without prompts — ideal for CI and scripted bootstraps:

./install.sh --api-key "sk-..." --provider openrouter

# Or via environment variables
REVKA_API_KEY="sk-..." REVKA_PROVIDER="openrouter" ./install.sh

install.sh flags

Flag	Purpose
--guided / --no-guided	Force interactive mode on or off
--install-system-deps	Install the OS compiler/build toolchain
--install-rust	Install Rust via rustup when missing
--prefer-prebuilt	Download a pre-built binary first, fall back to source
--prebuilt-only	Binary only; no source fallback
--force-source-build	Disable the pre-built path entirely
--docker	Docker/Podman bootstrap mode
--skip-build	(Docker mode) reuse a local image or pull from GHCR
--skip-install	Build only; do not install the binary
--api-key <key>	Skip the API-key prompt
--provider <id>	Provider name (default: openrouter)
--model <id>	Model ID override
--cargo-features <list>	Extra Cargo feature flags for the source build
--skip-onboard	Skip provider/API-key configuration
--install-sidecars / --skip-sidecars	Control the Python MCP sidecar install
--with-session-manager	Also install the Node.js Session Manager sidecar

Useful environment variables: REVKA_API_KEY, REVKA_PROVIDER, REVKA_MODEL, REVKA_CARGO_FEATURES, REVKA_CONTAINER_CLI, REVKA_DOCKER_DATA_DIR, REVKA_DOCKER_IMAGE, REVKA_BOOTSTRAP_MIN_RAM_MB, REVKA_BOOTSTRAP_MIN_DISK_MB, and REVKA_SKIP_VERIFY.

Run ./install.sh --help to see the complete list.

Tip

install.sh (and setup.bat) auto-install the Kumiho and Operator Python MCP sidecars under ~/.revka/ when a source checkout is present and the launchers are missing. Skip them with --skip-sidecars, or install them later — see Install the Python MCP sidecars.

Pre-built binaries & signature verification

The bootstrap (and revka update) detect your platform and download the matching release asset from GitHub Releases.

Target matrix

Target triple	Platform
x86_64-unknown-linux-gnu	Linux x86-64
aarch64-unknown-linux-gnu	Linux ARM64 (Raspberry Pi 4/5, 64-bit)
armv7-unknown-linux-gnueabihf	Linux ARMv7 (Raspberry Pi 2/3)
arm-unknown-linux-gnueabihf	Linux ARMv6
x86_64-apple-darwin	macOS Intel
aarch64-apple-darwin	macOS Apple Silicon
aarch64-linux-android	Android ARM64 (Termux)

musl / Alpine

Pre-built binaries are not published for musl/Alpine yet. On those systems the installer falls back to a source build, and --prebuilt-only fails fast.

Verification

Every downloaded archive is verified against the SHA256SUMS file published in the same release. If cosign is installed, the installer also verifies the keyless signature on SHA256SUMS (SHA256SUMS.sig + SHA256SUMS.pem) against the GitHub OIDC identity:

• Issuer: https://token.actions.githubusercontent.com
• Identity: the KumihoIO/Revka release workflow

If cosign is absent, the SHA256 checksum is still enforced and signature verification is skipped with a notice. To bypass all verification (not recommended), set REVKA_SKIP_VERIFY=1.

Homebrew (macOS / Linuxbrew)

The simplest path on macOS and Linux:

brew install revka
brew upgrade revka
brew uninstall revka

Homebrew places the binary at /opt/homebrew/bin/revka (Apple Silicon) or /usr/local/bin/revka (Intel) and uses a var/revka/ directory for runtime data, so you can run Revka as a launchd service:

brew services start revka

Note

Homebrew installs store config and workspace data under the Homebrew prefix (e.g. /opt/homebrew/var/revka/) rather than ~/.revka/. revka onboard warns if the config you write differs from the service config path. If both a Homebrew and a Cargo install exist, run which revka and revka --version to confirm which binary is active. See macOS update & uninstall.

Windows

setup.bat

From the repository root, the interactive script auto-detects your environment and walks you through installation:

setup.bat

Skip the menu with a mode flag:

Flag	Build
--prebuilt	Download the pre-compiled binary (fastest)
--minimal	Default features only
--standard	Matrix + Lark/Feishu + Postgres
--full	All features

setup.bat checks RAM (warning below 2 GB), checks for Rust, and invokes cargo install. It targets x86_64-pc-windows-msvc.

Scoop

scoop bucket add revka https://github.com/KumihoIO/scoop-revka
scoop install revka

Manual build

rustup target add x86_64-pc-windows-msvc
cargo build --release --locked --features channel-matrix,channel-lark --target x86_64-pc-windows-msvc
copy target\x86_64-pc-windows-msvc\release\revka.exe %USERPROFILE%\.revka\bin\

Prerequisites

Requirement	Required?	Notes
Git	Yes	git-scm.com/download/win
Rust 1.87+	Yes	Auto-installed by setup.bat if missing
Visual Studio Build Tools	Yes (source builds)	C++ workload — required for the MSVC linker
Node.js	No	Only needed to build the web dashboard from source

Visual Studio Build Tools

Source builds on Windows require the MSVC linker, which ships with Visual Studio Build Tools. If you don’t already have Visual Studio with the C++ workload:

1. Download from visualstudio.microsoft.com/visual-cpp-build-tools.
2. Select the “Desktop development with C++” workload.
3. Install, then restart your terminal.

If your build fails with linker errors, this missing workload is almost always the cause. If cargo build runs out of memory, use setup.bat --prebuilt to download a binary instead.

Post-install (Windows)

1. Restart your terminal so PATH changes take effect.
2. Initialize Revka: revka onboard
3. Configure your API key in %USERPROFILE%\.revka\config.toml.
4. Start the gateway + dashboard at http://127.0.0.1:42617: revka gateway (or run the full runtime with revka daemon).

Note

Running Revka as a persistent Windows service uses Task Scheduler — see revka gateway, daemon & service.

Source build (any platform)

When you need compile-time features, build directly with Cargo. The build is reproducible with --locked, and --features selects integrations:

cargo build --release --locked --features hardware,channel-matrix
cargo install --path . --force --locked

On constrained machines, cap parallelism to avoid out-of-memory failures:

CARGO_BUILD_JOBS=1 cargo build --release --locked

See Cargo feature flags & ADRs for the full feature list, and Network deployment, Raspberry Pi & proxy for ARM/embedded builds (--features hardware,peripheral-rpi).

Docker

Two published multi-arch images live on GitHub Container Registry:

• ghcr.io/kumihoio/revka:latest — distroless (no shell), minimal attack surface. Entrypoint: revka daemon.
• ghcr.io/kumihoio/revka:debian — Debian bookworm-slim with bash, git, and curl. Use this when the agent needs shell-based tools.

docker run -d \
  -e API_KEY=sk-... \
  -e PROVIDER=openrouter \
  -v revka-data:/revka-data \
  -p 42617:42617 \
  ghcr.io/kumihoio/revka:latest

Common environment variables: API_KEY (or REVKA_API_KEY), PROVIDER (default openrouter), REVKA_MODEL, REVKA_GATEWAY_PORT (default 42617), and REVKA_ALLOW_PUBLIC_BIND=true (required for container networking). The container runs as UID 65534 (nobody) with HOME=/revka-data.

The canonical liveness check (also used by the image HEALTHCHECK) is:

docker exec revka revka status --format=exit-code

Caution

The distroless image has no shell, so agent shell tools (ls, git, etc.) will fail — use :debian when those are needed. On some ARM64 platforms the distroless variant may exit immediately; fall back to :debian there too.

For the bootstrap-driven Docker flow:

./install.sh --docker
REVKA_CONTAINER_CLI=podman ./install.sh --docker   # Podman

This builds a local image and runs onboarding in a container, persisting data to ./.revka-docker (override with REVKA_DOCKER_DATA_DIR). Podman runs are issued with --userns keep-id and :Z volume labels automatically.

Restarting containers

Do not re-run install.sh to restart a container — it rebuilds the image and re-runs onboarding. Use docker start / docker compose up -d against the persisted data directory instead.

For Compose, one-click PaaS templates (Coolify, Dokploy, EasyPanel), and full container reference, see Docker, Compose & one-click PaaS.

Verify your install

After any install path, confirm the binary works and the environment is healthy:

revka --version
revka doctor          # structured config / workspace / environment diagnostics
revka self-test       # full diagnostic suite
revka self-test --quick   # offline checks only

revka doctor validates your config file, provider, API key, workspace, sidecars, and CLI tools — run it first whenever something looks off. See revka doctor, status & self-test.

Next steps

Onboarding wizard Run revka onboard to configure your provider, model, channels, and memory backend.

Quickstart Start the gateway, send your first message, and watch the audit chain verify.

Install the Python MCP sidecars Set up the Kumiho and Operator MCP sidecars Revka expects alongside the binary.

Docker, Compose & one-click PaaS Production container deployment, Compose, and Coolify/Dokploy/EasyPanel templates.