Installation & Updates

Install Kunobi, pick the release channel that fits your workflow, and let the app keep itself up to date. Kunobi runs on macOS, Windows, and Linux.

Release channels

Kunobi publishes to two channels in parallel:

• Stable - fully tested releases. Recommended for most users.
• Unstable - RC, beta, and alpha builds for early adopters who want features before they ship to stable. The Unstable channel also receives every stable release, so you always have the newest build.

Both channels share the same product identifier and the same in-app auto-update settings, so installing one replaces the other. Kunobi picks a default channel from the version you install (a 1.2.3 build defaults to Stable; a 1.2.3-rc1 build defaults to Unstable), and you can change it later in Settings → Update Channel. See Release Channels for a full comparison.

Install Kunobi

The commands below cover the first install or opting in to a channel. Switching channels after install happens inside the app.

With a package manager

The fastest way to install Kunobi is via a package manager. The Downloads page always shows the exact commands for your platform.

Homebrew (macOS)

Stable:

brew install --cask kunobi-ninja/kunobi/kunobi

Unstable:

brew install --cask kunobi-ninja/kunobi/kunobi-unstable

The unstable build ships from a separate kunobi-unstable cask in the kunobi-ninja/homebrew-kunobi tap.

apt (Linux)

Stable:

curl -fsSL https://r2.kunobi.com/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/kunobi.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/kunobi.gpg] https://r2.kunobi.com/apt stable main" \
  | sudo tee /etc/apt/sources.list.d/kunobi.list
sudo apt update
sudo apt install kunobi

Unstable:

curl -fsSL https://r2.kunobi.com/apt/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/kunobi.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/kunobi.gpg] https://r2.kunobi.com/apt unstable main" \
  | sudo tee /etc/apt/sources.list.d/kunobi.list
sudo apt update
sudo apt install kunobi-unstable

The unstable distribution also receives stable releases (since they're newer than pre-releases); unstable releases stay in unstable only.

winget (Windows)

Stable:

winget install kunobi-ninja.kunobi

Unstable:

winget install kunobi-ninja.kunobi.Unstable

Each channel has its own manifest in microsoft/winget-pkgs.

Chocolatey (Windows)

Stable:

choco install kunobi

Unstable:

choco install kunobi --pre

Chocolatey recognizes -rc, -beta, and -alpha suffixes as pre-releases; the --pre flag opts into them on the same package id.

aqua (cross-platform)

aqua init
aqua g -i kunobi-ninja/kunobi
aqua i

aqua resolves versions from GitHub tags directly. To use an unstable build, pin a pre-release tag (e.g. 1.2.3-rc1) in your aqua.yaml.

mise (cross-platform)

mise use aqua:kunobi-ninja/kunobi

Like aqua, mise resolves from GitHub tags. Pin a pre-release tag for unstable builds (e.g. mise use aqua:kunobi-ninja/kunobi@1.2.3-rc1).

Direct download

Open the Downloads page, or click Downloads in the top navigation bar, to download the installer for your platform directly. Use the Stable / Unstable toggle at the top of the page to choose your channel before downloading.

macOS

1. Download the .dmg file
2. Open it and drag Kunobi to your Applications folder
3. Launch Kunobi from Applications

Windows

1. Download the installer
2. Run it and follow the installation wizard
3. Launch Kunobi from Start Menu or Desktop shortcut

Linux

1. Choose the package format that fits your distribution
2. For .deb:

   sudo dpkg -i Kunobi_*.deb
   sudo apt-get install -f  # fix dependencies if needed

3. For .AppImage, mark it executable and run it
4. For .rpm, install with your system package manager

Keep Kunobi updated

Kunobi updates itself in place, so you rarely need to reinstall.

How updates work

• Kunobi checks for updates automatically when you launch the app and periodically while it runs.
• When an update is available, the version button in the status bar (bottom-right corner) shows a pulsing green download indicator. Click it to read the release notes and install.
• Updates download in the background, and the app restarts to finish installing.
• The update check sends your app version, platform, architecture, release channel, and install method, plus a random session identifier used for update analytics. It does not send your account, cluster, or file data.

For the full update walkthrough with screenshots, see Release Channels - How Updates Work.

Switch channels

Change your channel at any time in Settings → Update Channel. The change takes effect on the next update check.

• Stable to Unstable takes effect as soon as the next RC or stable build is published.
• Unstable to Stable only affects future updates. Because the updater never downgrades, moving to Stable right away means reinstalling a stable build from the Downloads page. If you can wait, the next stable release will bring you back to the stable line automatically.

Troubleshooting

An update isn't appearing

1. Check your internet connection.
2. Confirm your channel in Settings → Update Channel.
3. Trigger a manual check from the version button in the status bar.
4. You may already be on the latest build for your channel.

An update failed to install

1. Make sure you have enough free disk space.
2. Confirm Kunobi can write to its install directory.
3. Restart Kunobi and check again, or download the latest build manually from the Downloads page.

Next steps

With Kunobi installed, head to Connecting to Clusters to connect your first cluster, or spin up a local demo cluster to explore the interface.