Installation Guide

1 Prerequisites & System Requirements

MXE has two components: the Hub (your desktop app) and the Satellite (a tiny Rust binary on your server). Here's what each needs:

2 Download & Install the Hub

Windows

1. Go to the latest GitHub release and download the .exe installer
2. Run the installer — Windows SmartScreen may warn because it's unsigned; click "More info" → "Run anyway"
3. Follow the wizard — choose your install directory and click Install
4. Launch MXE from your Start Menu or desktop shortcut

Linux

1. Download the .AppImage from the latest GitHub release
2. Make it executable and run:

3 Your First Launch

When you first open MXE, you'll see the Dashboard. It'll be empty — that's normal! No servers are connected yet.

Here's what you're looking at:

• Header bar — Clock, portal status, and the Settings gear icon
• Server grid — Where your connected server cards will appear
• Activity log — Real-time event feed at the bottom
• Global HALT button — The red emergency stop (we'll get to that)

Don't worry about the empty state. In a few minutes, you'll have live server cards with real CPU/memory stats streaming in.

4 Configure API Keys (Optional)

MXE's AI features (log triage, Commander Chat, and agent integration) require an API key from either Anthropic or OpenRouter. This step is optional — MXE works fine without AI, you just won't get automatic log analysis or agent spawning.

Getting an API Key

• Anthropic: Sign up at console.anthropic.com, go to API Keys, and create one
• OpenRouter: Sign up at openrouter.ai, go to Keys, and create one

Adding it to MXE

1. Click the gear icon in the top-right of the dashboard
2. Select your provider (Anthropic or OpenRouter)
3. Paste your API key
4. Click Save

5 Deploy Your First Satellite

This is where the magic happens. You're going to put a tiny Rust binary on your VPS that will securely accept commands from your Hub.

What You'll Need

• Your VPS IP address or hostname (e.g., 203.0.113.5)
• Your SSH username (usually root)
• Path to your SSH private key (e.g., ~/.ssh/id_ed25519)

GUI Method (Recommended)

1. Click "Slide Satellite" in the dashboard header
2. Fill in:
   • Username: root (or your SSH user)
   • Host: Your VPS IP or domain
   • SSH Key Path: ~/.ssh/id_ed25519
   • SSH Port: 22 (default)
3. Click Deploy
4. Watch the real-time deploy log. MXE will:
   • Create a ~/.mxe directory on your server
   • Upload the Satellite binary via SCP
   • Launch it in the background
   • Capture the 6-digit pairing code
   • Auto-pair your Hub to the Satellite
5. When it's done, a new server card appears on your dashboard!

CLI Method (For Terminal Lovers)

6 Understanding Pairing & Connections

When the Hub and Satellite "pair," they exchange Ed25519 public keys and verify each other's identity using a 6-digit code. This is similar to Bluetooth pairing — it's a one-time trust establishment.

After pairing:

• Every command from Hub to Satellite is cryptographically signed
• The Satellite verifies the signature before executing anything
• Connection credentials are saved and encrypted locally
• On app restart, the Hub auto-reconnects to all saved Satellites

You'll see the server card status change:

• Pairing — Exchanging keys
• Connecting — Establishing WebSocket
• Online — Connected and streaming stats
• Offline — Connection lost (auto-reconnect in progress)

7 Using the Dashboard

Now that you're connected, your dashboard is alive! Here's what everything does:

Server Cards

Each connected Satellite gets a card showing:

• CPU sparkline — Real-time CPU history chart, updated every 30 seconds
• Memory & Disk — Color-coded stats: green is good, amber means watch it, red means it's hot
• Service tags — Detected services (nginx, mysql, docker, etc.)
• Status dot — Connection health at a glance
• Ghost cache indicators — Staleness badges show when data was last refreshed

Click any server card to open the 7-tab detail modal:

• Overview — System info, uptime, OS, hostname
• Repos — Discovered git repositories with deep scan (runtimes, databases, git log)
• Services — Running web/db/cache services with versions
• Processes — Top processes by CPU with kill buttons
• AI Tools — Detected AI CLI tools (Claude Code, Codex, Gemini, Aider)
• Health — Checklist: disk usage, system load, memory pressure, zombie processes
• Agents — Spawn and monitor AI agents in remote repos

Repo Pinning

Found an important repo? Pin it to the dashboard for quick access. Pinned repos surface above the fold so you always see their status at a glance.

Portal Management

Right-click or use the menu on any server card to manage its portal connection:

• Edit — Change connection details
• Copy host:port — Quick clipboard copy
• Remove — Disconnect and delete saved credentials

Activity Log

The scrolling log at the bottom shows everything happening in real-time:

• Info — Normal operations (connections, stats, deploys)
• Warning — Something to keep an eye on
• Critical — Something needs attention (auto-triaged by AI if configured)
• Action Result — Output from executed commands

Emergency Halt (DEFCON 1)

The red GLOBAL HALT button in the header is the panic button. It:

1. Sends a kill signal to every connected Satellite
2. Terminates all running processes on each Satellite
3. Clears all in-memory secrets
4. Confirms the kill from each Satellite in the log

8 Talking to the Commander

Click the Commander toggle in the dashboard header to open the chat sidebar. This is your conversational interface to your entire fleet.

Try these prompts:

• Check disk space on all servers
• What's the nginx status?
• Restart the failed service on production
• Run a security audit on /var/www/mysite

The Commander can delegate commands to your Satellites. When it does:

1. It generates a bash command
2. The Hub signs it with Ed25519
3. The Satellite verifies and executes it
4. Results come back and the Commander analyzes them
5. It can chain up to 5 commands automatically (ReAct loop)

Commander Chat now supports markdown rendering for formatted responses and command history — press up/down to recall previous prompts.

Safety Toggle

When the Commander or triage system suggests a fix, the safety toggle controls whether it executes automatically or requires your confirmation:

• Assisted mode (default) — AI suggests, you approve with one click
• Hands-free mode — AI suggests and executes (still blocklist-protected)

9 Agent Integration

MXE v introduces the ability to spawn AI agents directly into remote repositories on your Satellites. This is the "Agentic" in Agentic Command Center.

How It Works

1. Open the 7-tab server modal and navigate to the Agents tab
2. Select a discovered repository on that server
3. Click Spawn Agent to launch a Claude Code instance into that repo
4. The agent runs on the remote server with full access to the repo — reading files, running tests, making changes
5. All agent commands flow through the Portal with Ed25519 signing and blocklist protection

What Agents Can Do

• Read and understand codebases
• Run tests and diagnose failures
• Make code changes and create commits
• Investigate production issues in context

10 Developer Setup (Building from Source)

Want to run MXE locally for development or contribute? Here's the full setup.

Requirements

• Node.js 20+ — nodejs.org
• Rust toolchain — curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• just (command runner) — cargo install just

Clone & Install

Run Everything Locally

Run the Tests

Useful Commands

11 Troubleshooting

Satellite won't start

Pairing fails

• Make sure the 6-digit code matches exactly (codes are single-use)
• Verify port 9077 is open: ufw allow 9077
• Check that the Satellite is actually running: ps aux | grep mxe-satellite
• Try connecting directly: curl -v http://YOUR_IP:9077 (should get a WebSocket error — that's good!)

Connection keeps dropping

• Check your network stability between Hub and Satellite
• MXE auto-reconnects with exponential backoff (1s → 2s → 4s → ... → 30s cap)
• If it keeps failing, check the Satellite's memory usage — it has a 256MB limit in systemd

AI triage not working

• Open Settings and verify your API key is saved
• MXE falls back to a mock evaluator if no key is configured
• Check the activity log for API errors

Agents won't spawn

• Verify your API key is configured (Settings gear icon)
• Make sure the target repo was discovered (check the Repos tab)
• Check that the Satellite has sufficient resources (agents need CPU and memory)

Need more help?