# 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](/docs/under-the-hood/container-topology/), 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](https://github.com/speednet-software/speedwave/releases/latest). 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](/docs/security/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

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.

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:

```powershell
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.

<DesktopFrame screen="setup" />

## 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](/docs/understand/how-it-works/) for what runs where, and [start your first project](/docs/get-started/first-project/) to put it to work.

## Confirm it works

After setup, open a terminal and run:

```bash
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](/docs/security/securitycheck/) for what these checks cover.