Beta is for testing. It gets new transports first, including AmneziaWG and OpenVPN over Cloak, and is rebuilt more often, so it can break. Beta Desktop and Terminal images are both published on this track. Right after a stable release the two tracks can carry the same version, because stable is promoted from the beta that was tested rather than rebuilt from scratch; when the version shown here matches the Stable tab there is nothing newer to gain from beta, so take Stable. Beta moves ahead again at the next cut. Switching a running system between tracks is covered step by step under Binaries.
Beta images are for testing. They are rebuilt often and can break. If you want a system to rely on, take the Stable ISO and point APT at the beta repository afterwards, which is covered under Binaries.
Beta images are for testing. They are rebuilt often and can break. If you want a system to rely on, take the Stable ISO and point APT at the beta repository afterwards, which is covered under Binaries.
Install Kodachi Binaries
The signed Kodachi APT repository is the recommended install and update path for Debian, Ubuntu, and Kodachi. Two commands to install, one to update. Choose your system below and copy. Everything else is under Only if you need it.
ISO users: binaries already included
You do not need this pack if you installed the Kodachi Desktop or Terminal ISO. Both editions already ship with the binaries built in.
You only need this pack to update the binaries when a newer binaries release is published but the Desktop or Terminal ISO has not been rebuilt yet.
Only if you need it
Switch between stable and betatwo commands, either direction
Both setup scripts write the same source file, /etc/apt/sources.list.d/kodachi.sources, so running one replaces the other. Nothing is uninstalled and your configuration is left alone. The commands below were measured end to end on a clean Debian 13 install, in both directions.
Stable to beta
1Point APT at the beta repository
curl -fsSL https://kodachi.cloud/repo-beta/setup.sh | sudo sh
The /beta suffix is what does the work. Beta carries newer software under a lower version string than stable, and APT will not pick a lower version on its own at a normal repository priority, so a plain apt upgrade or apt install kodachi reports already the newest version and changes nothing. Naming the release explicitly overrides that, and --allow-downgrades then permits it.
Beta back to stable
1Point APT back at the stable repository
curl -fsSL https://kodachi.cloud/repo/setup.sh | sudo sh
2Move the installed packages back
sudo apt update && sudo apt install kodachi
No extra flag is needed in this direction. Stable’s version string is the higher one, so returning is an ordinary upgrade and the six core components come back on their own.
Checking without changing anything:
sudo apt update && apt list --upgradable
This lists what your current channel is offering and installs nothing. It is not a way to preview the other channel: while you are on stable it will not show the beta packages, for the same reason a plain apt upgrade will not install them, so an empty list here does not mean beta has nothing newer.
Two things to know either way. Beta installs three packages stable does not carry, kodachi-amneziawg-dkms, kodachi-amneziawg-tools and kodachi-cloak-client, which provide AmneziaWG and OpenVPN over Cloak. Returning to stable leaves them installed and working but no longer updated; sudo apt autoremove clears them if you want a clean stable box, or leave them if you expect to go back. And kodachi-pihole is dropped by the switch, because it pins the exact kodachi-hooks-core version it was built against, and it is not reinstalled automatically on the way back. If you use Pi-hole, run sudo apt install kodachi-pihole after switching in either direction.
Install one package instead of the full suitedashboard, AI, conky, privacy tools
Package
Purpose
kodachi
Full suite for Debian 13, Ubuntu 24.04, and Kodachi.
kodachi-hooks-core
Command-line VPN, Tor, DNS, authentication, integrity, and core services without the desktop app.
kodachi-ai
Local-first AI suite. APT pulls the shared core automatically.
kodachi-dashboard
Native desktop dashboard. Requires glibc 2.39 or newer.
kodachi-conky
On-screen status widget. APT pulls the shared core automatically.
Individual privacy tools are also available as standalone packages, including kodachi-xray, kodachi-hysteria, kodachi-mieru, kodachi-v2ray, kodachi-v2ray-plugin, kodachi-kloak, and kodachi-dnscrypt.
Remove or purge an installationapt suite, core and AI, or portable
Full suite:
sudo apt remove kodachi # remove only the metapackage
sudo apt purge kodachi # purge only the metapackage configuration
sudo apt autoremove --purge # review APT's list before confirming
The component packages installed as dependencies remain after removing or purging only the kodachi metapackage. Run apt autoremove --purge only after reviewing APT's proposed list, because it removes every automatically installed package that APT now considers unused.
Core and AI:
sudo apt remove kodachi-hooks-core kodachi-ai
sudo apt purge kodachi-hooks-core kodachi-ai
sudo apt autoremove --purge # review APT's list before confirming
Portable (Fedora, Arch, other):
There is nothing for APT to remove, because the portable route never registered a package. The installer has no uninstall option either, so removal means deleting what it created. Every path below is one the installer writes; read the list before you run it, and drop any line for a component you did not install.
If you installed with --path or --desktop, replace /opt/kodachi with the directory you chose. Unless you passed --skip-path, also delete the block between # BEGIN KODACHI PATH and # END KODACHI PATH in your ~/.bashrc. The system dependencies from step 2 are ordinary distribution packages and are left alone; remove them with your own package manager if you want them gone too.
Which systems are supportedfull suite, core only, portable
Full suiteDebian 13, Ubuntu 24.04, and Kodachi. Includes the native dashboard, core services, AI suite, desktop integration, and recommended privacy tools.
Core and AI onlyDebian 12 and Ubuntu 22.04. Not supported on the stable track: every Kodachi package on it requires glibc 2.39, which these releases do not have. Switch to the beta track above, or upgrade to Debian 13 or Ubuntu 24.04.
Portable binariesFedora, Arch, and other modern x86_64 Linux systems. Use the portable installer; step 2 of that tab carries a ready dnf command for Fedora and the dependency list to translate for anything else.Stable only. The portable installer always fetches the published stable binary pack, so it cannot deliver beta. On beta, use the APT route on a Debian-family release.
Offline tarballadvanced, air-gapped installs
Optional: manual / offline tarball (advanced)
For air-gapped or offline setups only. The terminal install above is the recommended method for all standard installations.
The offline tarball is built from the published stable release metadata, so there is no beta equivalent to download. Its version, build number and SHA-256 describe the stable pack and would be wrong here, which is why it is hidden on this track.
To run beta, use the APT route above: point APT at the beta repository and install from it. For an offline beta machine, install the stable tarball first, then switch that machine to beta over APT when it next has network access, as covered under Switch between stable and beta.
Debug Collector
If you encounter issues with your Kodachi installation, the Debug Collector gathers system diagnostics into a single zip file you can share with the support team. It collects boot logs, hardware specs, network configuration, Kodachi service status, and more.
Privacy First
The collector does not capture browsing data or personal files. Passwords, passphrases, API keys, private keys, authentication headers and VPN credentials are stripped before anything is written to the archive, and again in a final pass over the whole bundle. That includes the WireGuard and AmneziaWG keys that identify which server you connect to, not only the ones that would let someone connect as you. WiFi network names (SSIDs) and MAC addresses are replaced with placeholders. Public IP addresses, both IPv4 and IPv6, are redacted; private LAN, loopback and link-local addresses are kept, because a network problem cannot be diagnosed without them. You can also deselect specific categories before collection starts.
Run the debug collector (interactive category menu):
