Linux and WSL2

toryo provides its CLI fleet on Linux and inside a WSL2 distribution. A Linux desktop app is built in three formats for x64 and arm64: a .deb for Debian and Ubuntu, an .rpm for Fedora, and an .AppImage that runs on any distribution without being installed. Which of them a given release carries is what that release lists, so check the downloads page rather than assuming all three. Only the .AppImage updates itself in place; a .deb or .rpm install updates through its package manager.

The desktop packages have not been tried inside WSL2. Windows has an unsigned installer for the desktop app; see Windows.

Install#

On Windows, open the Ubuntu terminal or its Windows Terminal profile and run this Linux CLI installer there, not in PowerShell. Opening Ubuntu alone does not install toryo. Board defaults new distributions to Ubuntu-24.04; if you selected another supported WSL2 distribution, use its terminal instead.

curl -fsSL https://raw.githubusercontent.com/ForceBuilders/toryo-releases/main/install.sh | sh

The installer selects the x64 or arm64 Linux archive, verifies its checksum, extracts it under ~/.toryo/bin, then runs setup and installs agent skills. Inside WSL2 it identifies the environment and uses the same Linux artifact. Installer overrides, including version, home, release channel, setup, and skills, are documented in Getting started.

The installer needs curl and either sha256sum or shasum. minisign is strongly recommended because Linux has no OS-level artifact signature. The installer verifies the signed checksum list when minisign is available and warns when it is not; toryo update carries its own verifier.

Supported distributions#

The desktop .deb installs on Debian 12 and later and on Ubuntu 22.04 LTS and later. Ubuntu 20.04 is not supported: its archive carries no libwebkit2gtk-4.1-0, which the package depends on, so apt refuses the install outright rather than leaving a half-working one behind.

The desktop .rpm targets Fedora. It declares the same webkit and GTK requirement, as the shared libraries themselves rather than as package names, so dnf refuses an install it cannot satisfy rather than leaving one that will not launch. On Fedora 41 those two libraries resolve to webkit2gtk4.1 and gtk3.

RHEL 9 and its derivatives (Rocky, Alma) are not supported by the .rpm. Their base repositories carry webkit2gtk3, which is the WebKitGTK 4.0 API, and nothing there provides libwebkit2gtk-4.1.so.0. The dependency is what refuses the install, so the failure is a clear dnf error rather than a package that installs and then will not start. Use the .AppImage on those distributions.

What sets that floor is the webkit dependency, not glibc. The desktop binary needs at most glibc 2.34 and the bundled CLI at most 2.17, both below every distribution in the list, so a newer C library is never the reason an install fails.

The .AppImage is the option for everything else. It installs nothing, so it carries no package dependency at all; it wants a FUSE-capable host, and --appimage-extract-and-run covers a host without one.

The CLI archives carry no such dependency and run wherever they extract.

Flatpak and Snap are not planned#

Neither is on the roadmap, and the reason is what toryo does rather than a question of effort. toryo drives the host: it spawns tmux, git, docker and the agent harness CLIs, reads and writes the repositories you point it at, and manages user systemd units. A Flatpak or a Snap runs those under a sandbox that has none of them, so the bundle either ships with enough holes punched in it (--filesystem=host, full socket access, the host's whole PATH) that the sandbox no longer means anything, or it works for nothing anyone installs it for.

The .AppImage is the answer to the question those formats usually get asked, a single file that runs on any distribution. It has no sandbox to defeat.

Services and database#

Setup installs foreman watch as a user systemd unit where a user bus is available. Otherwise it adds a guarded shell-start block. WSL2 commonly needs systemd enabled in /etc/wsl.conf before the user-unit path works; toryo doctor reports the active supervisor path and its problems.

Linux defaults to pglite, so Docker is not required. Choose Docker during setup for heavier concurrency. The stores are separate, so changing runtimes later requires a dump and restore to carry data across.

On WSL2, keep repositories and ~/.toryo in the Linux filesystem rather than under /mnt/c; worktree and git I/O across the mount is substantially slower.

Verification boundary#

The release gate runs the Linux installer in a container and exercises setup, doctor, pglite, migrations, service startup, and concurrent reads. A second gate installs the .deb on each Debian and Ubuntu release in the list above, checks that the desktop binary resolves every shared library it needs, and runs the bundled CLI. That gate installs with apt only, so the .rpm is built and checksummed without an install of its own being exercised. That is more than unit coverage, but it is not evidence for every host integration.

On Windows 11, the installer, WSL2 and Ubuntu setup, CLI installation and the services have been run end to end; see Windows. Real Linux hardware and the complete supervisor lifecycle through a real user systemd bus remain unverified. Hardware-specific agent and Docker behavior remains part of that boundary. After successful CLI installation, report failures with toryo doctor --json inside Ubuntu on Windows (or your selected WSL2 distribution); see Feedback.