Skip to content

Installation

Jump to bottom
dEXploarer edited this page Mar 27, 2026 · 2 revisions

Installation

This page covers every supported installation path. Pick the path that matches your environment.

Prerequisites

Requirement Minimum version Notes
Node.js 22.12.0 The installer will offer to install via nvm, fnm, or your distro package manager
npm or bun any current npm ships with Node; bun is optional but preferred for build speed
curl or wget any Required only for the shell installer

The .nvmrc in the repo pins Node 22. If you use nvm, running nvm use inside the repo directory will select the correct version automatically.

Option 1 — Shell installer (macOS / Linux / WSL / Git Bash)

curl -fsSL https://milady-ai.github.io/milady/install.sh | bash

What the script does, in order:

  1. Detects your OS, architecture, and shell environment (WSL, Git Bash, MSYS2, etc.)
  2. Checks for Node.js >= 22.12.0 and offers to install it if missing
  3. Detects your package manager (npm preferred; bun if MILADY_USE_BUN=1)
  4. Runs npm install -g miladyai (or bun install -g miladyai)
  5. Runs milady setup to initialize your workspace

Environment variables for the installer

Variable Effect
MILADY_SKIP_SETUP=1 Skip the milady setup step after install
MILADY_USE_BUN=1 Use bun instead of npm for installation
MILADY_VERSION=<ver> Install a specific version instead of latest
MILADY_LOCAL_TARBALL=<path> Install from a local .tgz file (dev/testing)
MILADY_NONINTERACTIVE=1 Skip all interactive prompts (assume yes)

Node.js auto-install strategy (per OS)

If Node.js is missing or too old, the installer tries:

  • macOS: nvm (if present) → fnm (if present) → Homebrew (brew install node@22) → MacPorts → offers to install nvm
  • Linux: nvm (if present) → fnm (if present) → distro package manager (NodeSource apt/rpm, apk, pacman, zypper) → offers to install nvm
  • Windows (Git Bash / MSYS2 / WSL): fnm → nvm-windows → winget → Chocolatey → Scoop → offers to install fnm

Option 2 — PowerShell installer (Windows, native)

irm https://milady-ai.github.io/milady/install.ps1 | iex

Use this for native Windows PowerShell. The bash installer will not work without Git Bash, MSYS2, WSL, or Cygwin.

Option 3 — npm global install

npm install -g miladyai
milady setup

The package name on npm is miladyai. The CLI binary is registered under multiple aliases: milady, milady.ai, milady-ai, miladyai, and milaidy.

Option 4 — bun global install

bun install -g miladyai
milady setup

Option 5 — Homebrew (macOS / Linux)

brew tap milady-ai/milady
brew install milady          # CLI
brew install --cask milady   # Desktop app (macOS only)

Option 6 — Snap (Linux)

sudo snap install milady
milady setup

Snap packages auto-update in the background. Available on Ubuntu, Fedora, Manjaro, and any distro with snapd installed.

For the latest development builds:

sudo snap install milady --edge

Option 7 — Flatpak (Linux)

flatpak install flathub ai.milady.Milady
flatpak run ai.milady.Milady

Or sideload from a release bundle:

flatpak --user install milady.flatpak

Option 8 — Debian / Ubuntu (APT)

# Add the repository
curl -fsSL https://apt.milady.ai/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/milady.gpg
echo "deb [signed-by=/usr/share/keyrings/milady.gpg] https://apt.milady.ai stable main" | \
  sudo tee /etc/apt/sources.list.d/milady.list

# Install
sudo apt update && sudo apt install milady

Works on Debian 12+, Ubuntu 22.04+, Linux Mint 22+, Pop!_OS, and other Debian derivatives. Updates come through apt upgrade.

Option 9 — Build from source

git clone https://github.com/milady-ai/milady.git
cd milady
bun install
bun run build
bun run milady start

The bun install step runs a postinstall script that initializes git submodules, ensures skill/avatar assets are present, links the browser server, and patches certain dependencies (see scripts/patch-deps.mjs). Do not skip it.

The build script (scripts/rt.sh) prefers bun but falls back to npm automatically. To force Node-only: bun run build:node

For hot-reload dev mode: bun run dev

Option 10 — Desktop app

Download signed and notarized binaries directly from GitHub Releases:

Platform File
macOS (Apple Silicon) Milady-arm64.dmg
macOS (Intel) Milady-x64.dmg
Windows Milady-Setup.exe
Linux Milady.AppImage or .deb
iOS App Store
Android Google Play / APK

The shell installer can also download and install the macOS desktop app:

curl -fsSL https://milady-ai.github.io/milady/install.sh | bash -s -- --desktop

This downloads the correct .dmg for your architecture, mounts it, copies the .app to /Applications, and removes the quarantine attribute. The --desktop flag is macOS-only via this script; Windows users should download the .exe from Releases directly.

Verifying downloads

cd ~/Downloads
curl -fsSLO https://github.com/milady-ai/milady/releases/latest/download/SHA256SUMS.txt
shasum -a 256 --check --ignore-missing SHA256SUMS.txt

First run

After any install method, run:

milady setup
milady

milady setup initializes the workspace at ~/.milady/ and walks you through onboarding (agent name, vibe, model provider, API key). On subsequent runs, milady setup can also be used to refresh your workspace after an update.

Once running, the dashboard is available at http://localhost:2138 and the Gateway WebSocket at ws://localhost:18789/ws.

Workspace location

All user data lives in ~/.milady/:

  • ~/.milady/milady.json — main config file (JSON5, owner-read-write only, mode 0600)
  • ~/.milady/.env — optional secrets file
  • ~/.milady/workspace/ — elizaOS runtime workspace
  • ~/.milady/logs/ — log files (used in headless/daemon mode)
  • ~/.eliza/skills.json — local skills extra-directory config (auto-created on first run)

Updating

Re-run the installer or:

npm install -g miladyai@latest
milady setup

milady setup after an update refreshes the workspace for any structural changes introduced in the new version.

Clone this wiki locally