Distribution anatomy

The release archive 404-distro.tar.gz is a WSL-importable root filesystem exported from an Alpine image. wsl --import registers it under a chosen name and creates a local installation directory. The managed desktop path uses 404; the self-hosted guide uses 404-cli to avoid a collision. These names identify WSL distributions, not different STATIC implementations.

Files and dependencies

distro/Dockerfile.build starts from alpine:3.19, installs bpftool, iproute2, and libgcc, copies the staged musl STATIC binary and ttl_editor.o into /opt/404/, and marks the executable and launcher runnable. distro/build.sh adds /opt/404/distro-version, builds a temporary image, then uses docker create and docker export | gzip -n to produce the tarball. The archive is a rootfs, not an installer that configures Windows trust or proxy settings.

/etc/wsl.conf sets default=root and automount options. It does not have a boot command. Entering the distro with wsl -d <name> opens a Linux shell; it does not by itself launch STATIC. The Windows CLI guide invokes the launcher explicitly.

Where configuration comes from

The fallback /opt/404/404-init.sh reads /opt/404/win-user, set by the operator or app. It looks for static.runtime.toml under the Windows user’s AppData/Roaming/com.404.app/static/ directory, then the legacy AppData/Roaming/404/static/ path. The config references profiles in that Windows-mounted directory. The script stops if no config exists rather than running STATIC without a selected profile.

The published operator ZIP stages the legacy AppData/Roaming/404/static/ path, three profiles, a local control-token file, manifest files, and the distro tarball. The managed desktop path has its own app-data layout. Avoid assuming the two paths share a single CA or profile store merely because they run the same binary.

Startup and packet attachment

someguy is documented to start STATIC explicitly after preparing configuration and eBPF state. The fallback/manual launcher instead attempts the following:

  1. Ensure bpffs is mounted and create the /sys/fs/bpf/404 directory.
  2. Load or attach ttl_editor.o through bpftool and tc on active eth* interfaces, or interfaces named by EGRESS_IFACES.
  3. Pin the fingerprint_profiles map at /sys/fs/bpf/404/fingerprint_profiles.
  4. Execute /opt/404/static --config <mounted TOML> --mode proxy.

The attach path is best effort. A missing tool, wrong interface, or unavailable pin can leave the proxy running without effective packet mutation; STATIC separately attempts to sync its selected packet profile into the pinned map. Follow the eBPF packet path for packet layouts, classifier scope, and wire checks instead of treating process readiness as packet fidelity.

Listener and trust crossing WSL2

The operator runtime TOML binds proxy port 4040 and control port 4042 inside the distro. Windows browsers reach the local proxy through WSL’s forwarding behavior. STATIC’s public CA certificate is generated in the distro, but Windows must trust that public certificate before a Windows browser accepts intercepted HTTPS. The Linux file-backed private key remains inside the distro. See CA and trust for the trust boundary and API for the token-protected control listener.

Sources: Dockerfile, packaging script, fallback launcher, WSL config, and release workflow.