# AetherDesk Linux — "Linux for Windows" distro kit

AetherDesk can package itself as a real named WSL2 distro: **AetherDesk-Linux**.
After install it sits next to Ubuntu and friends in `wsl -l`, boots an Alpine
userland with Node.js and AetherDesk preinstalled, and serves the desktop at
`http://127.0.0.1:5717` for the Windows browser.

## Build the kit

```powershell
npm run linux:distro
```

This writes the kit to `artifacts/aetherdesk_linux_distro/` (no network needed):

| File | Role |
| --- | --- |
| `Install-AetherDeskLinux.ps1` | Windows installer: download, verify, `wsl --import`, provision |
| `setup-aetherdesk.sh` | In-distro provisioner: packages, user, repo checkout, launcher, `/etc/wsl.conf` |
| `aetherdesk-linux-distro.json` | Kit manifest with SHA-256 digests of every generated file |
| `AETHERDESK_LINUX_README.md` | Operator instructions for the Windows side |

The kit is also inspectable at runtime via `GET /api/linux/distro` and the
**Distro Kit** button in the Linux Shell app window.

## Install on Windows

```powershell
powershell -ExecutionPolicy Bypass -File .\Install-AetherDeskLinux.ps1
```

The installer:

1. Requires WSL (`wsl --install` guidance if missing).
2. Refuses to touch an already-registered `AetherDesk-Linux` — it never
   unregisters or overwrites a distro; removal is a manual
   `wsl --unregister AetherDesk-Linux`.
3. Downloads the Alpine minirootfs (latest-stable, x86_64) from the official
   Alpine CDN and verifies its SHA-256 against the published
   `latest-releases.yaml` manifest before import.
4. Imports it as a WSL2 distro under `%LOCALAPPDATA%\AetherDesk\Linux`.
5. Pipes `setup-aetherdesk.sh` into the distro as root: installs Node.js, npm,
   git, bash; creates the `aether` default user; clones AetherDesk into
   `/opt/aetherdesk/app`; installs runtime dependencies; writes the
   `aetherdesk` launcher and `/etc/wsl.conf`.

Offline installs: pre-download the minirootfs tarball and pass
`-RootfsPath C:\path\to\alpine-minirootfs-...tar.gz -RootfsSha256 <hex>`.

## Use

```powershell
wsl -d AetherDesk-Linux              # Linux shell as user 'aether'
wsl -d AetherDesk-Linux -- aetherdesk  # start AetherDesk (port 5717)
```

WSL2 forwards localhost, so the Windows browser reaches the distro-hosted
AetherDesk at `http://127.0.0.1:5717`.

## Boundaries

- The installer only writes inside the chosen install directory and only
  downloads from `dl-cdn.alpinelinux.org` over HTTPS with checksum verification.
- No secrets are read, written, or embedded anywhere in the kit.
- Uninstall stays a deliberate manual step (`wsl --unregister`), matching the
  repo rule that destructive operations need explicit human action.

## Tests

```powershell
npx vitest run tests/aetherdesk/linux-distro.test.ts
```
