Mage-OS Installer

September 12, 2026 · View on GitHub

Get up & running with Mage-OS in minutes. If you have DDEV or Warden installed already, this tool will automatically detect and configure them for you.

Features

  • Automatically detects available development environments
  • Configures services (OpenSearch, Redis, RabbitMQ, Varnish) out of the box

Supported environments

EnvironmentSite URL
DDEVhttps://{project}.test
Wardenhttps://app.{project}.test

Prerequisites

  • Docker installed and running
  • At least one supported environment installed (DDEV or Warden)

Installation

Download the latest binary for your platform from the releases page.

macOS (Apple Silicon)

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_darwin_arm64
sudo chmod +x /usr/local/bin/mage-os-install

macOS (Intel)

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_darwin_amd64
sudo chmod +x /usr/local/bin/mage-os-install

Linux (x86_64)

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_linux_amd64
sudo chmod +x /usr/local/bin/mage-os-install

Linux (ARM64)

sudo curl -sL -o /usr/local/bin/mage-os-install https://github.com/mage-os-lab/mage-os-installer/releases/latest/download/mage-os-install_linux_arm64
sudo chmod +x /usr/local/bin/mage-os-install

Windows

Download mage-os-install_windows_amd64.exe (or mage-os-install_windows_arm64.exe) from the releases page and add the directory to your PATH.

Via Go

go install github.com/mage-os-lab/mage-os-installer@latest

Usage

Run the installer from the directory where you want your project:

mage-os-install

The installer will walk you through:

  1. Project name -- defaults to the current directory name

  2. Install directory -- where to create the project

  3. Prerequisites -- Docker running, the Mage-OS repository reachable, git and sudo available

  4. Environment selection -- pick DDEV or Warden (auto-selected if only one is available)

  5. Admin credentials -- configure the Mage-OS admin user

  6. Command review -- inspect the setup:install flags before running

  7. Installation -- watch progress in real time

  8. Environment selection -- pick DDEV or Warden (auto-selected if only one is available)

  9. Admin credentials and store settings -- the admin user, plus locale, timezone and currency detected from your machine

  10. Command review -- inspect the setup:install flags before running

  11. Installation -- watch progress in real time

Progress is saved to .mage-os-install.json in the project directory after every step. If an install stops partway, running the installer again in that directory offers to resume from the first unfinished step; your settings come back pre-filled and only the admin password (and Hyvä token) are asked for again. The file is removed once the install completes.

Scripting it

Every answer can be given as a flag, and --yes runs the install without the interface, which is what CI and demo scripts want:

mage-os-install --yes --project my-shop --admin-password 'S0mething-long-enough' \
  --admin-email me@example.com --sample-data

Without --yes the same flags pre-fill the screens. --env ddev or --env warden picks the environment when both are installed; --git=false skips the repository; --hyva needs --hyva-repo-url and --hyva-auth-token. Run mage-os-install -h for the full list. A non-interactive run exits with status 1 and the reason when something is missing or the install fails.

Wishlist

  • Save & reuse a config profile (~/.mage-os-install.yaml) so re-running skips prompts.
  • Non-interactive / scripted mode via flags or a config file (useful for CI and demos).