WSL Distribution (linxira-wsl)
Why it exists
A good share of Linxira's target users — developers who work with AI agents — spend their days on Windows while the agent's execution environment is Linux. Maintaining dual boot or a virtual machine for them is expensive; WSL2 is the native answer on the Windows side. linxira-wsl brings the Linxira toolchain into WSL as a rootfs distribution: no kernel, firmware or bootloader (WSL ships its own), only the parts that are actually used in a terminal.
Responsibilities
It owns:
- Building the rootfs
tar.gzand matching.sha256used bywsl --import/wsl --install --from-file. - The package manifest
wsl-packages.x86_64, the default/etc/wsl.conf(wsl.conf) and the read-only pre-release gateverify-wsl-rootfs.sh. - Deciding which first-party tools go into the image, and what is deliberately left out (kernel, firmware, bootloader, NetworkManager, Zeta).
It does not own:
- A desktop ISO; that is
linxira-iso-direct, and this image is not published with the ISO. - Building the packages themselves; they come from the
packagesrepository and are distributed through[linxira]. - WSL networking; name resolution, proxies and hosts are the Windows side's job.
- Component transaction planning and execution;
linxira-componentsis the single implementation of that chain.
Relation to the desktop edition
| ISO install | WSL | |
|---|---|---|
| Kernel / boot / partitioning | handled by the installer | not applicable (WSL ships the kernel) |
| Desktop | catalog choice (KDE Plasma / COSMIC / headless with full toolset / minimal headless) | no session; GUI tools via WSLg (Win11) |
| Software stack | chosen at install time / component-manager | linxira-component-manager or linxira-config stack (the same chain) |
| Workspace guard | timer every 30 minutes | not enabled by default (see below) |
| Network management | NetworkManager | managed on the Windows side; the image deliberately installs no NetworkManager |
| Zeta | full binary package (desktop route) | not shipped; use the npm package @linxiraos/zeta, which needs nodejs / npm installed first |
What the workspace guard means in WSL: a WSL VM is shut down by Windows when no process is running, and systemd timers only fire while it runs — "a snapshot every 30 minutes" degrades into "a snapshot while a session is active". The image therefore leaves the guard off by default. Users who want it can run sudo linxira-config workspace-guard enable manually, but should understand the trigger conditions.
Usage
wsl --import linxira C:\wsldata linxira-wsl-<version>-x86_64.tar.gz --version 2
wsl -d linxira
# remove
wsl --unregister linxira
After import the default user is root, systemd is enabled (/etc/wsl.conf sets systemd=true, default=root and hostname=linxira), the [linxira] repository uses the same configuration as the ISO install (with signature verification), and linxira-update works out of the box.
The image ships no Node runtime. For the terminal flavour of Zeta:
sudo pacman -S nodejs npm
npm i -g @linxiraos/zeta
Contents
The full list is wsl-packages.x86_64 in the repository, currently 37 explicit entries (more than three hundred packages after dependency resolution; installed and compressed sizes are whatever the build script's closing du -sh prints). Three groups:
- Base and everyday CLI:
base,curl,ca-certificates(declared explicitly; the build asserts that the root certificate store exists and holds a sane number of certificates),git,wget,nano,less,man-db,man-pages,bash-completion,unzip,zip,which,rsync,dnsutils,jq,fastfetch,openssh,sudo,btrfs-progs,archlinux-keyring,linxira-keyring. - First-party toolchain and brand assets:
linxira-components,linxira-component-manager,linxira-config(Config Hub),linxira-recovery-diagnostics,linxira-update,linxira-wiki,linxira-catalog,linxira-completion-agent,linxira-crash-watch,linxira-hooks,linxira-gaming-manager,linxira-hardware-driver-manager,linxira-package-center,linxira-welcome,linxira-artwork. - Deliberately absent: kernel, firmware and bootloader; NetworkManager; the Zeta binary package; any Node runtime; any desktop session.
linxira-update depends on Qt6 (python-pyqt6, qt6-svg), so its window can display directly under Win11 + WSLg.
Network
The image ships no DNS, proxy or hosts overrides: /etc/hosts and /etc/resolv.conf are generated by WSL, and resolution is delegated to the Windows side. "Some sites do not open" on mainland networks is usually a host-side cause. The most common one is an accelerator such as Steam++ / Watt Toolkit writing domains into the Windows hosts file pointing at 127.0.0.1; WSL2 receives those addresses through the Windows resolver, and inside WSL 127.0.0.1 is the WSL VM itself, so the connection is refused. This is not a certificate problem — the image's root store matches Arch's.
To make an accelerator or proxy work inside WSL, pick one:
- Mirrored networking (recommended, Win11 22H2+): add
[wsl2]/networkingMode=mirroredto%UserProfile%\.wslconfig, thenwsl --shutdown; - Explicit proxy:
export HTTPS_PROXY=http://<Windows host IP>:<port>(for NAT mode the host IP is the nameserver in/etc/resolv.conf), or put it in your shell startup file.
Privileges
- The default user is root, and the image ships
sudo. That matches official WSL distributions but also means there is no privilege separation by default. To use a normal account, create one and changedefaultin/etc/wsl.conf. - Installing packages with pacman and running component transactions need root;
linxira-config workspace-guard enableneeds root. - Read-only queries (
linxira-config status,linxira-crash status,linxira-config workspace-guard status) need no root.
Known limitations
- No desktop session; graphical tools display only under Win11 + WSLg, and on Win10 they are CLI-only.
- An idle WSL VM is shut down by Windows, and systemd timers only fire while it runs; the workspace guard is therefore off by default and its snapshot semantics are weaker than on the desktop.
- The image is still in development; the repository rules forbid calling test artifacts a release. The release path is GitHub Releases (
linxira-wsl-<YYYY.MM.DD>-x86_64.tar.gzplus.sha256). - Not published with the ISO and not part of the desktop ISO build chain.
- No DNS/proxy/hosts overrides; check the host side first when networking fails.
- Root by default with no pre-created normal user; multi-user isolation is your configuration to make.
Building
On Arch (or in an Arch container):
sudo pacman -S --needed arch-install-scripts
./build-wsl-rootfs.sh
LINXIRA_MIRROR=https://mirrors.aliyun.com/archlinux ./build-wsl-rootfs.sh
- Build on ext4: never build against
/mnt/cor/mnt/f(9p/drvfs) — character and block device nodes cannot be created there, and the whole pacstrap/chroot/tar chain is an order of magnitude slower. The script probes withfindmntand exits 65 on 9p/drvfs;LINXIRA_ALLOW_DRVFS=1is for troubleshooting only. - Avoid
/tmp(tmpfs is RAM): a measured incident — packing the rootfs filled a 2 GB tmpfs and a parallel ISO build on the same machine was OOM-killed. - During the build the
[linxira]repository usesSigLevel = Never, only to break the bootstrap problem that the keyring itself ships inside the packages; the final/etc/pacman.confwritten into the image uses exactly the same signature-verification configuration as the ISO install. - Before publishing, run the read-only gate:
./verify-wsl-rootfs.sh out/linxira-wsl-<YYYY.MM.DD>-x86_64.tar.gz
It checks licences, brand assets, the fastfetch identity, catalog component entries, the crash-watch service and diagnose-crash skill, Linxira package versions, /usr/share/licenses/<pkg>/ for every first-party package, and the root certificate count; any failure exits non-zero.
Further design
Repository and build notes are in the linxira-wsl README.md; the package manifest and build constraints are wsl-packages.x86_64 and AGENTS.md in the same repository.