Magpie AI Installation Guide

System Requirements#

Download Magpie AI only from the official website usemagpie.ai, GitHub Releases (github.com/yetone/magpie), or official repository sources. Any site, app, or download page that asks for payment, account top-up, or login credentials should not be treated as an official Magpie AI source.

If you want the shortest decision path:

• One-Line Terminal Script (macOS / Linux): run the official automated curl script
• macOS Desktop: Homebrew Cask (brew install --cask magpie-app) or download the DMG
• Go Developers / Cross-Platform: go install github.com/yetone/magpie@latest
• Windows: prefer MSI installer; use portable zip for quick trial use
• Linux / Servers: prefer the curl script or official Docker container

Fastest Install: Official Automated Script (macOS / Linux)#

This is the recommended installation path. The script auto-detects your CPU architecture (Apple Silicon / Intel / Linux x64 / ARM64) and installs the latest binary:

# Official one-line installation
curl -fsSL https://usemagpie.ai/install.sh | sh

If you are behind a corporate firewall or experience network timeouts connecting to GitHub, you can append a proxy flag:

# Proxy acceleration mode
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890

Once installed, simply type magpie or magpie tui in your terminal to start.

Prerequisites#

The CLI tools managed by Magpie AI, including Claude Code, Codex, and Gemini CLI, require Node.js.

Recommended version:

• Node.js 18 LTS or later

If you are only installing the Magpie AI desktop app, Node.js is not the blocker. But if you want Magpie AI to manage Claude Code, Codex, or Gemini CLI right after install, it is better to prepare Node.js first.

Install Node.js on Windows

1. Open the official Node.js website
2. Download the LTS installer
3. Run the installer and finish setup
4. Verify the installation:

node --version
npm --version

If both commands print versions normally, Node.js and npm are available in your environment.

Install Node.js on macOS

# Install with Homebrew
brew install node

# Or use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

If you may switch Node versions later, nvm is more flexible. If you just want the fastest path, Homebrew is simpler.

Install Node.js on Linux

# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# Or use nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

If you already have your own Node workflow on Linux, keep using it; the commands here are mainly the shortest path for a first-time setup.

Install CLI Tools#

The goal here is not to install every CLI at once. For a first pass, you usually only need one CLI that you want Magpie AI to manage.

Claude Code

On macOS, you can try:

brew install claude-code

General npm install:

npm install -g @anthropic-ai/claude-code

# Use a mirror if downloads are slow
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

After installation, run:

claude

to confirm the command is available.

Codex

On macOS, you can try:

brew install codex

General npm install:

npm install -g @openai/codex

# Use a mirror if downloads are slow
npm install -g @openai/codex --registry=https://registry.npmmirror.com

After installation, run:

codex

to confirm the command can start.

Gemini CLI

On macOS, you can try:

brew install gemini-cli

General npm install:

npm install -g @google/gemini-cli

# Use a mirror if downloads are slow
npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com

After installation, run the startup command you normally use locally to make sure it is available in PATH.

If npm downloads are often slow on your network, you can set the registry first:

npm config set registry https://registry.npmmirror.com

Install Magpie AI on Windows#

Installer package

1. Open the Releases page
2. Download Magpie-v{version}-Windows.msi
3. Double-click the installer
4. Finish the setup flow
5. Launch Magpie AI from the Start menu or desktop

Best for:

• most first-time users
• people who want the standard Windows installation path
• people who want simpler updates and removal later

Portable build

1. Download Magpie-v{version}-Windows-Portable.zip
2. Extract it to any folder
3. Run Magpie.exe

Notes:

• keep it in a stable folder rather than a temporary downloads location
• better for trial use than as the default long-term setup path

Install Magpie AI on macOS#

Method 1: Homebrew (Official Cask)

# Install the macOS Menu Bar App
brew install --cask magpie-app

To upgrade later:

brew upgrade --cask magpie-app

Best for:

• people who already manage tools with Brew
• people who prefer command-line upgrades

Method 2: Manual download

1. Download Magpie-v{version}-macOS.dmg The DMG is the recommended choice, though Magpie-v{version}-macOS.zip is also available.
2. Open the DMG, or unzip the archive to get Magpie AI.app
3. Drag the app into Applications

The macOS build is code signed and notarized, so it should normally open directly.

If this is your first install and you want the least setup overhead, the DMG path is usually simpler than preparing Homebrew first.

Install Magpie AI on Linux#

Arch Linux

Use an AUR helper:

# With paru
paru -S magpie-bin

# Or with yay
yay -S magpie-bin

If you already use paru or yay for desktop tooling, this is the most natural path.

Debian / Ubuntu

1. Download the correct package for your architecture: Magpie-v{version}-Linux-x86_64.deb or Magpie-v{version}-Linux-arm64.deb
2. Install it:

sudo dpkg -i Magpie-v{version}-Linux-*.deb

# If dependencies need to be fixed
sudo apt-get install -f

Suggestions:

• use the x86_64 package on x86_64 machines
• use the arm64 package on ARM devices
• after install, try launching the app directly from the menu or terminal

AppImage (generic)

1. Download the correct AppImage for your architecture: Magpie-v{version}-Linux-x86_64.AppImage or Magpie-v{version}-Linux-arm64.AppImage
2. Make it executable:

chmod +x Magpie-v{version}-Linux-*.AppImage

3. Run it:

./Magpie-v{version}-Linux-*.AppImage

Best for:

• people who do not want to think about distro-specific package formats first
• quick validation before committing to a longer-term install method

If you end up using Magpie AI long-term, you can still move later to a more distro-native package path.

Docker Container Deployment (Headless & NAS)

If you are running on a headless server, NAS, or containerized developer pod, run Magpie using the official distroless container:

docker run -d \
  --name magpie \
  --restart unless-stopped \
  -p 3425:3425 \
  -v ~/.magpie:/root/.magpie \
  ghcr.io/yetone/magpie

Once running, point any coding agent on the same machine or local network to http://127.0.0.1:3425/v1.

Android Termux Environment

Magpie also runs smoothly inside Termux on Android, providing a portable model gateway for mobile developers:

# 1. Install prerequisites
pkg update && pkg install golang git

# 2. Build and install latest version
go install github.com/yetone/magpie@latest

# 3. Launch the terminal interface
magpie tui

Verify the Installation#

After installation, run these baseline checks to ensure both your CLI environment and local gateway are ready:

1. Terminal Commands:
   bash

   # Check installed Magpie version
   magpie --version
   
   # List detected AI agents
   magpie ls
   

2. Terminal TUI Dashboard: Run magpie tui, confirm that the split-pane dashboard renders cleanly, and exit anytime with q.
3. Menu Bar Status (Desktop): Verify that the Magpie status icon is visible in your macOS menu bar or Windows/Linux tray.
4. Gateway Health Probe: Visit http://127.0.0.1:3425/health in your browser or curl it. An HTTP 200 with {"status":"ok"} confirms the local translation gateway is operating smoothly.

After this, the usual next step is to configure your first provider and test one real request.

Automatic Updates#

Magpie AI includes built-in update support:

• it checks for updates on startup
• update prompts appear in the UI when a new version is found
• you can click the prompt to download and install it

You can also check manually in:

• Settings → About

Uninstall#

Windows

• uninstall from Settings → Apps
• or run the uninstaller from the install directory

macOS

1. Move Magpie AI.app to Trash
2. Optionally remove the config directory if you want a full cleanup:

~/.magpie/

Linux

# Debian / Ubuntu
sudo apt remove magpie

# Arch Linux
paru -R magpie-bin

If you are only upgrading, you do not need to uninstall first unless the current installation is clearly broken or you are deliberately switching install methods.

FAQ#

Q: What should I do if macOS says the app is "damaged" or "cannot be verified"?

A: This is gatekeeper protection. Open "System Settings -> Privacy & Security", scroll down to find the warning, and click "Open Anyway".

Q: What if Windows SmartScreen blocks the installer?

A: Click "More info" in the warning dialog, then select "Run anyway" to proceed with the installation.

Q: What should I do if the curl script times out?

A: If network access to GitHub is restricted, append a local proxy flag to the installer: curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890 (replace with your local proxy port), or compile directly via Go: go install github.com/yetone/magpie@latest.