Skip to main content

Operations runbook — Windows Installer

This guide describes how to use the unified Windows installer to set up a local AlphaSwarm environment quickly.

Overview​

The windows-install.ps1 script automates the following steps:

  1. Verifies the Windows environment.
  2. Installs system dependencies via winget: Python 3.11, Node.js, Terraform, k3d, and kubectl.
  3. Installs pnpm via npm.
  4. Assists with Docker Desktop installation.
  5. Sets up a Python virtual environment (.venv) at the workspace root.
  6. Installs core AlphaSwarm packages in editable mode:
    • alphaswarm_core
    • alphaswarm_agents
    • alphaswarm_auth
    • alphaswarm_controller
    • alphaswarm (monolith)
    • alphaswarm_cli
  7. Installs frontend dependencies for alphaswarm_client.
  8. Generates the local configuration (.env.local).
  9. Verifies the installation using alphaswarm-cli setup verify.

Prerequisites​

  • A PC running Windows 10 (version 1809 or later) or Windows 11.
  • Administrator privileges (to run winget and install system tools).
  • winget (App Installer) installed from the Microsoft Store.
  • Git installed and the AlphaSwarm repositories cloned into a single workspace directory.

Installation​

  1. Open PowerShell as an Administrator.

  2. Navigate to your AlphaSwarm workspace root:

    cd path\to\alphaswarm-workspace

  3. Set the execution policy to allow running the script (if not already set):

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process

  4. Run the installer:

    .\alphaswarm_platform\scripts\windows-install.ps1

  5. Follow the prompts. If Docker is not installed, the script will install it and ask you to launch it manually.

Post-Installation​

After the script completes successfully:

  1. Activate the virtual environment:

    .\.venv\Scripts\Activate.ps1

  2. Start the local development stack:

    cd alphaswarm
    # If you have 'make' installed:
    make dev
    # Otherwise, use the direct docker command provided at the end of the installer script.

  3. Access the applications:

Troubleshooting​

winget not found​

Ensure you have the "App Installer" from the Microsoft Store. Recent versions of Windows 10 and all Windows 11 versions include it by default.

Script execution disabled​

If you get an error about scripts being disabled, run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process in your PowerShell session before running the installer.

Docker not found or not running​

Ensure Docker Desktop is running and WSL2 is enabled if required. The script needs a working Docker daemon to manage local containers.

Python Version Conflicts​

The script targets Python 3.11 specifically via winget. If you have multiple versions, ensure the one in .venv is used (which the script handles by using absolute paths during installation).

Known gap: the alphaswarm monolith package's pyproject.toml declares requires-python = ">=3.12" (the other five editable installs — alphaswarm_core, alphaswarm_agents, alphaswarm_auth, alphaswarm_controller, alphaswarm_cli — only need >=3.11). Installing alphaswarm[dev,auth,cli,paper] into the Python-3.11 .venv the script creates will fail with a "requires a different Python" error from pip. Until the installer is updated, install a 3.12 interpreter (winget install --id Python.Python.3.12) and either point the script's venv creation at it or re-create .venv with py -3.12 -m venv .venv before step 6.