Install Speedwave

Speedwave runs on macOS and Windows. It installs everything it needs to run containers, so you do not install Docker Desktop, a container runtime, or any virtualization tooling yourself. Linux is not a supported host platform.

Before you start

	Minimum	Recommended
RAM	16 GiB	32 GiB
Free disk	10 GiB	20 GiB

Speedwave still starts below the minimum, but performance can suffer. On macOS, Speedwave checks host RAM at startup and warns under 16 GiB, then sizes its VM to about half your host RAM, so a 16 GiB Mac gets an 8 GiB VM. Windows has no RAM detection: Speedwave always assumes 16 GiB there, so this warning never fires on Windows regardless of your actual RAM, and WSL2 manages memory on its own.

Download

Every release is published on GitHub Releases. Pick the install package for your machine from the latest release’s assets:

Platform	Hardware	Install package
macOS	Apple Silicon	Speedwave_<version>_macOS_Apple_Silicon.dmg
macOS	Intel	Speedwave_<version>_macOS_Intel.dmg
Windows 10 and 11	64-bit	Speedwave_<version>_x64-setup.exe, or the .msi for managed IT deployment

Installers are signed; see binary authenticity if you want to verify a download before running it.

Windows also needs hardware virtualization enabled in the BIOS or UEFI (Windows runs containers under Hyper-V) and administrator rights for the first install, so Speedwave can set up WSL2.

Install

macOS

1. Open the downloaded .dmg and drag Speedwave into your Applications folder.
2. Launch Speedwave once from Launchpad. macOS verifies the app’s signature on first run.
3. The setup wizard creates Speedwave’s virtual machine using Apple’s built-in virtualization framework, so there is nothing else to install.

On Apple Silicon, Speedwave uses Rosetta to run x86 container images, so images built for either architecture work.

Windows

1. Run the downloaded .exe installer.
2. Launch Speedwave from the Start menu.
3. If WSL2 is missing, the setup wizard installs it for you. You will see a Windows permission prompt, then need to restart your PC and open Speedwave again.
4. The wizard sets up a dedicated WSL2 distribution named Speedwave and starts the container runtime inside it.

The Speedwave WSL2 distribution is separate from any Linux distributions you already run, and Speedwave does not change your default WSL setup.

If the automatic WSL2 setup fails on a locked-down machine, enable it by hand from an elevated PowerShell, then reopen Speedwave:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
wsl --update

Note

Windows 11 version 22H2 (build 22621) or later is needed only if you work behind a corporate VPN and want Speedwave to reach VPN-routed services from inside the container. Speedwave checks your build number at startup and warns below 22621 (silently skipped if the build number can’t be read). On older builds Speedwave still runs; only VPN-routed traffic stays unreachable from the container.

Welcome to Speedwave.

first-run setup · ~2 minutes

✓check environmentdone

✓start virtual machinedone

3build imagesrunning

4create your first project

5start containers

6finalize

What the wizard does

The wizard tracks six steps, saving progress to ~/.speedwave/setup_state.json so an interrupted run resumes instead of starting over: check environment, start VM, build images, create your first project, start containers, and finalize (link the speedwave CLI). Once it finishes, there is nothing left to install or set up per project. See how Speedwave works for what runs where, and start your first project to put it to work.

Confirm it works

After setup, open a terminal and run:

speedwave check

On a healthy system you get:

speedwave check OK -- all system checks passed

speedwave check validates your system and Speedwave’s container configuration against its security rules. It only reports; it does not start containers or change anything. If a check fails, the command prints the failing rule and a hint, then exits with an error. Fix the issue and run it again. See SecurityCheck and its rules for what these checks cover.