404PrivacyDocs

Windows installation

The Windows CLI path runs STATIC inside a 404 Linux distribution on WSL2. These steps use a separate distro named 404-cli so it does not collide with the managed desktop application’s 404 distro. Run the PowerShell commands in PowerShell on Windows, not inside WSL, unless a step says otherwise.

1. Check WSL2

In PowerShell, run:

wsl --status
wsl --list --verbose

If WSL is not installed, follow Microsoft’s WSL installation guide and restart when prompted. The import below explicitly requests WSL version 2. This guide is for Windows x64.

2. Download and extract the bundle

Download 404-windows-x64.zip from the latest release. Save it to Downloads, then extract into your Windows home folder:

Expand-Archive -LiteralPath "$HOME\Downloads\404-windows-x64.zip" -DestinationPath "$HOME" -Force
Get-Item "$HOME\404-distro.tar.gz", "$env:APPDATA\404\static\static.runtime.toml", "$env:LOCALAPPDATA\404\wsl\control-token"

The archive contains the distro tarball, its manifest and signature, the runtime config, three profiles, and a local control token. The hash check below confirms the tarball matches the bundled manifest; it does not authenticate the publisher.

$manifest = Get-Content "$HOME\404-distro-manifest.json" -Raw | ConvertFrom-Json
$archiveHash = (Get-FileHash "$HOME\404-distro.tar.gz" -Algorithm SHA256).Hash.ToLower()
if ($archiveHash -ne $manifest.sha256.ToLower()) { throw "Distro archive does not match the manifest" }
"Distro archive matches manifest version $($manifest.version)"

Stop if the check fails. Keep the control-token file private.

3. Choose a browser profile

Open the bundled config:

notepad "$env:APPDATA\404\static\static.runtime.toml"

It defaults to default_profile = "firefox-windows". Keep that for Firefox; use chrome-windows for Chrome or edge-windows for Edge. Save the file before importing or starting the distro.

4. Import and start the distro

$DistroName = "404-cli"
New-Item -ItemType Directory -Force "$env:LOCALAPPDATA\404\wsl" | Out-Null
wsl --import $DistroName "$env:LOCALAPPDATA\404\wsl\$DistroName" "$HOME\404-distro.tar.gz" --version 2
wsl -d $DistroName -- sh -lc "printf '%s\n' '$env:USERNAME' > /opt/404/win-user"
wsl -d $DistroName

Keep the distro running. Its boot script starts STATIC and attempts to attach supported Linux packet handling. The packaged environment uses Alpine sh; it does not assume bash.

In another PowerShell window, check the authenticated local control endpoint:

$token = (Get-Content "$env:LOCALAPPDATA\404\wsl\control-token" -Raw).Trim()
Invoke-RestMethod -Headers @{ "X-404-Control-Token" = $token } http://127.0.0.1:4042/status

If the endpoint is unavailable, check the first window for startup errors before changing your browser’s proxy settings.

5. Trust the generated CA

STATIC generates a local CA certificate when it starts. In the usual self-hosted root-user path, its public certificate is at:

$LiveCaPath = "\\wsl.localhost\$DistroName\root\.local\share\static_proxy\certs\static-ca.crt"
Get-Item $LiveCaPath

If that file exists, open the certificate in File Explorer, select Install Certificate, choose Current User, then Place all certificates in the following store → Trusted Root Certification Authorities. Never import or share static-ca.key.dpapi.

Firefox may need a separate import: Settings → Privacy & Security → Certificates → View Certificates → Authorities → Import. Select the same static-ca.crt and enable trust for identifying websites.

6. Route the browser and verify

STATIC listens at 127.0.0.1:4040 on the Windows side.

Open a normal HTTPS page in the configured browser. If you get a certificate error, confirm that the trusted certificate came from this running instance. If the page never loads, check the distro window and the /status command above. Turn off the manual proxy setting when STATIC is stopped.