Skip to main content

Operations runbook — macOS Installer

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

Overview​

The macos-install.sh script automates the following steps:

  1. Verifies the macOS environment.
  2. Installs Homebrew (if missing).
  3. Installs system dependencies: Python 3.11, Node.js 22, pnpm, yarn, Terraform, k3d, and kubectl.
  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_config
    • alphaswarm_core
    • alphaswarm_agents
    • alphaswarm_auth
    • alphaswarm_controller
    • alphaswarm (monolith)
    • alphaswarm_cli
    • alphaswarm_assistant
  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 Mac running macOS (Intel or Apple Silicon).
  • Administrator (sudo) privileges.
  • Git installed and the AlphaSwarm repositories cloned into a single workspace directory.

Installation​

  1. Navigate to your AlphaSwarm workspace root:

    cd path/to/alphaswarm-workspace

  2. Run the installer:

    ./alphaswarm_platform/scripts/macos-install.sh

  3. 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:

    source .venv/bin/activate

  2. Start the local development stack:

    cd alphaswarm
    make dev

  3. Access the applications:

Troubleshooting​

Docker not found or not running​

Ensure Docker Desktop is running and you have accepted the terms of service. The script requires a working Docker socket to build and run local containers.

Homebrew Permission Issues​

If Homebrew installation fails due to permissions, you may need to fix your /usr/local or /opt/homebrew ownership or run the Homebrew install command manually with appropriate permissions.

Python Version Conflicts​

The script specifically targets Python 3.11. If you have multiple Python versions installed, ensure python3.11 is available in your PATH after the script runs.