Install - Koya Documentation

Install Koya using a package for your distribution or a runtime archive below.

Packages #

Koya v0.7.1 (build 925) — download tarballs directly or use a distro package below.

Tarball	x86_64	aarch64
Koya Runtime (glibc)	tar.gz	tar.gz
Koya Runtime (musl)	tar.gz	tar.gz

x86_64 #

Package	Arch	RPM	DEB	Alpine / postmarketOS
Koya Runtime	pkg.tar.zst	rpm	deb	apk
All plugins	pkg.tar.zst	rpm	deb	apk
Hypr plugin	pkg.tar.zst	rpm	deb	apk
HTTP plugin	pkg.tar.zst	rpm	deb	apk
Process plugin	pkg.tar.zst	rpm	deb	apk
PAM plugin	pkg.tar.zst	rpm	deb	apk
DBus plugin	pkg.tar.zst	rpm	deb	apk
WebSocket plugin	pkg.tar.zst	rpm	deb	apk
SQLite plugin	pkg.tar.zst	rpm	deb	apk
FFmpeg plugin	pkg.tar.zst	rpm	deb	apk

aarch64 #

Package	Arch	RPM	DEB	Alpine / postmarketOS
Koya Runtime	pkg.tar.zst	rpm	deb	apk
All plugins	pkg.tar.zst	rpm	deb	apk
Hypr plugin	pkg.tar.zst	rpm	deb	apk
HTTP plugin	pkg.tar.zst	rpm	deb	apk
Process plugin	pkg.tar.zst	rpm	deb	apk
PAM plugin	pkg.tar.zst	rpm	deb	apk
DBus plugin	pkg.tar.zst	rpm	deb	apk
WebSocket plugin	pkg.tar.zst	rpm	deb	apk
SQLite plugin	pkg.tar.zst	rpm	deb	apk
FFmpeg plugin	pkg.tar.zst	rpm	deb	apk

Manual install #

Place binary at /usr/bin/koya
Ensure vulkan-icd-loader and GPU drivers are installed
Wayland session required; no X11/Xorg

Note

No network features ship by default; install native modules to enable optional features.

Arch Linux (pacman) signing setup #

Install from URL requires trusting Koya's signing key once:

Then install directly:

Alpine / postmarketOS repository #

For apk-tools 3 or newer on x86_64 or aarch64, configure the Koya repository once and use APK for installs and updates. Packages use an Alpine 3.23 musl baseline. Keep your existing Alpine or postmarketOS system repositories for library dependencies. The tagged Koya repository supplies Koya and its plugins.

Authenticate the Alpine public key with the existing Koya OpenPGP key before trusting it. The setup below checks the OpenPGP fingerprint and verifies the Alpine key signature in a temporary keyring. APK then verifies the native signatures on the repository index and packages.

sudo apk add curl gnupg

# Run this setup in Bash.
set -e
setup=$(mktemp -d)
trap 'rm -rf -- "$setup"' EXIT
mkdir -m 700 "$setup/keyring"
base=https://www.koya-ui.com/downloads
for file in koya-packages.pub koya-apk.rsa.pub koya-apk.rsa.pub.sig; do
  curl -fsSL "$base/$file" -o "$setup/$file"
done
gpg --homedir "$setup/keyring" --show-keys --with-colons "$setup/koya-packages.pub" > "$setup/key-info"
# Accept exactly one primary key, with the known fingerprint.
test "$(awk -F: '$1 == "pub" { count++ } END { print count }' "$setup/key-info")" = 1
fingerprint=$(awk -F: '$1 == "fpr" { print $10; exit }' "$setup/key-info")
test "$fingerprint" = 06089A97B6D66C69BFD021F0DF7B60698EF57FF3
gpg --homedir "$setup/keyring" --import "$setup/koya-packages.pub"
gpg --homedir "$setup/keyring" --verify "$setup/koya-apk.rsa.pub.sig" "$setup/koya-apk.rsa.pub"
sudo install -m 644 "$setup/koya-apk.rsa.pub" /etc/apk/keys/koya-apk.rsa.pub

repo='v3 @koya https://www.koya-ui.com/repository/alpine'
grep -qxF "$repo" /etc/apk/repositories || printf '%s\n' "$repo" | sudo tee -a /etc/apk/repositories
sudo apk update
# Upgrade any plugins previously installed from downloaded APK files
# in the same transaction as the runtime and plugin bundle.
packages=(koya@koya helix-plugins@koya)
for plugin in dbus ffmpeg http hypr pam process sqlite ws; do
  name="helix-plugin-$plugin"
  if apk info --exists "$name"; then packages+=("$name@koya"); fi
done
sudo apk add "${packages[@]}"
koya --version

For the runtime alone, install koya@koya. Add a selected plugin with, for example, apk add helix-plugin-ffmpeg@koya. helix-plugins@koya installs all eight plugins. After setup, update with apk update followed by apk upgrade koya helix-plugins. Plugins depend on the exact matching Koya release. Use doas in place of sudo where appropriate.

If dependencies are unavailable on postmarketOS, resolve them through your existing system repositories. Do not add Alpine stable system repositories to postmarketOS edge or force installation.

Alpine Linux / postmarketOS #

Choose Alpine/postmarketOS APKs for musl-based Linux: aarch64 (ARM64) or x86_64 (Intel/AMD). These packages use an Alpine 3.23 baseline and require apk-tools 3 or newer. Your installed libraries must satisfy the package dependencies.

The koya package installs the runtime and assets. APK installs missing system libraries automatically from your configured repositories. helix-plugins installs all eight individual plugin packages, including FFmpeg and its codec dependencies. For only the core runtime, use koya alone in the download loop below. Plugins require the matching Koya release. Keep your existing working graphics driver.

For manual downloads, verify the detached OpenPGP signatures using the Koya public key before installing with --allow-untrusted. This also works for older releases without native APK signatures. The option bypasses native APK signature trust; dependency checks still apply. The Koya key fingerprint is 06089A97B6D66C69BFD021F0DF7B60698EF57FF3.

# Install the download and signature-verification tools.
sudo apk add curl gnupg

# Select packages for this machine.
arch=$(uname -m)
case "$arch" in
  aarch64|x86_64) ;;
  *) echo "Unsupported architecture: $arch"; exit 1 ;;
esac
mkdir -p koya-0.7.1-925-$arch
cd koya-0.7.1-925-$arch
base=https://www.koya-ui.com/downloads
curl -fLO "$base/koya-packages.pub"
gpg --import koya-packages.pub
gpg --fingerprint 06089A97B6D66C69BFD021F0DF7B60698EF57FF3
for name in koya helix-plugins helix-plugin-dbus helix-plugin-ffmpeg helix-plugin-http helix-plugin-hypr helix-plugin-pam helix-plugin-process helix-plugin-sqlite helix-plugin-ws; do
  file="$name-0.7.1-r925.$arch.apk"
  curl -fLO "$base/$file" && curl -fLO "$base/$file.sig" &&
    gpg --verify "$file.sig" "$file" || exit 1
done
sudo apk add --allow-untrusted ./*.apk
koya --version

Use doas instead of sudo if that is how your installation grants administrator access. If a dependency is unavailable, do not add Alpine stable repositories to postmarketOS edge or force installation. Check the missing library against your postmarketOS packages first.

<- Quickstart (60 seconds)Examples ->