Profiles, Runtime Modes & Customization

During real-world development, engineers frequently juggle diverse development environments:

• Work vs. Personal Projects: Corporate policies may mandate using internal enterprise model endpoints, whereas personal open-source projects thrive on cutting-edge models like DeepSeek V4 or advanced reasoning LLMs;
• Remote & Containerized Servers: In cloud development instances (Remote Dev Containers, headless Linux, or NAS devices), Magpie needs to run as a headless daemon listening across local subnets;
• Multi-Environment Orchestration: Power users want to swap the routing configuration of every installed assistant in a single command.

Magpie AI provides a lightweight yet robust Profiles engine, custom environment variables, daemon management, and TUI customization to fine-tune your workflow.

Feature 1: Profiles (Environment Snapshots)#

Magpie AI's profile system captures active agent bindings, provider endpoints, and routing group rules into a named snapshot.

1. Save an Environment Snapshot

Once you have configured an ideal setup (e.g. Claude Code bound to DeepSeek and Codex bound to Kimi):

# Save active bindings under the "work" profile
magpie save work

# Save another setup for personal weekend projects
magpie save personal

2. Instant One-Command Environment Swaps

When transitioning contexts, use magpie use <profile>. Magpie surgically mutates dotfiles across all managed agents in milliseconds:

# Switch to corporate work configuration
magpie use work

# Switch back to personal open-source configuration
magpie use personal

3. List and Manage Profiles

# List all saved environment profiles
magpie profiles

# Delete an obsolete profile
magpie profile delete client-legacy

Feature 2: Gateway Parameters & Environment Variables#

Magpie AI's gateway listens on http://127.0.0.1:3425 by default. You can customize core parameters via ~/.magpie/config.yaml or system environment variables:

Example: Start Gateway on a Custom Port

# Launch Magpie gateway on port 5000
MAGPIE_PORT=5000 magpie start

Feature 3: Headless & Daemon Modes (Linux / Remote Dev)#

For remote development machines without graphical displays, Magpie AI functions as a headless background daemon:

1. Daemon Management Commands

# Start background daemon
magpie daemon start

# Check daemon health and process PID
magpie daemon status

# Stop background daemon
magpie daemon stop

# Restart and reload configuration
magpie daemon restart

2. Systemd Service Setup (Linux)

Create a systemd unit at /etc/systemd/system/magpie.service:

[Unit]
Description=Magpie AI Model Router Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/usr/local/bin/magpie start --headless
Restart=always
RestartSec=5
Environment=MAGPIE_HOST=0.0.0.0
Environment=MAGPIE_PORT=3425

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now magpie

3. Docker Deployment

Deploy using the official lightweight container image:

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

Feature 4: System Autostart & Menu Bar Preferences#

On macOS and Windows desktop environments:

1. Launch at Login: Run magpie autostart enable in your shell or toggle "Launch at Login" in desktop preferences. The gateway and menu bar status app launch automatically on boot.
2. Menu Bar Only Mode (macOS): Enable "Menu Bar Only" in preferences to suppress the macOS Dock icon, keeping Magpie quietly tucked away in your top menu bar.

Frequently Asked Questions#

Q: Does changing MAGPIE_PORT automatically update agent configurations?

A: When you re-apply bindings via magpie claude ... or magpie use <profile>, Magpie reads the current active MAGPIE_PORT and injects the updated port into agent configurations.

Q: How do I synchronize configurations across multiple workstations?

A: All Magpie provider definitions, routing groups, and privacy rules are stored as plain YAML inside ~/.magpie/. You can track ~/.magpie/config.yaml in your private dotfiles Git repository (make sure to avoid committing unencrypted API tokens to public repositories).

Q: How can I ensure Magpie runs reliably as a background service on headless Linux?

A: Manage Magpie using systemd (configuring Restart=always and WantedBy=multi-user.target, as demonstrated in Section 3) or run the official Docker container with --restart unless-stopped. The gateway will recover automatically within seconds following system reboots.