Skip to content

CONCEPTS.md

Latest commit

 

History

History
324 lines (249 loc) · 12.5 KB

CONCEPTS.md

File metadata and controls

324 lines (249 loc) · 12.5 KB

AI Maestro: Core Concepts

Understanding AI Maestro's architecture will help you maximize its potential for managing distributed AI coding agents.

Table of Contents

What is AI Maestro?

AI Maestro is a browser-based dashboard for managing multiple AI coding agents across one or more machines. Think of it as a "mission control" for your AI coding workforce.

The Problem It Solves

When working with Claude Code, you might:

  • Run multiple AI agents simultaneously (frontend, backend, testing, documentation)
  • Want to organize agents by project or purpose
  • Need to check on agent progress without switching tmux windows
  • Want to manage agents across different machines (local MacBook, remote Mac Mini, cloud servers)

AI Maestro centralizes all of this in one clean web interface accessible from any connected node.

Localhost vs Remote Hosts

Understanding the difference between localhost and remote hosts is crucial to leveraging AI Maestro's power.

Localhost (Local Host)

Localhost means "this computer" - the machine where AI Maestro is currently running.

Characteristics:

  • ✅ Always available (you're running on it)
  • ✅ No network required
  • ✅ Fastest performance (no network latency)
  • ✅ Most secure (no network exposure)
  • ⚠️ Limited to this machine's resources (CPU, RAM, GPU)

Example:

Your MacBook Pro running AI Maestro
  └─ Local agents: frontend-app, backend-api, docs-writer

When to use:

  • Single-machine development
  • Maximum security needs
  • Getting started with AI Maestro
  • Limited network access scenarios

Remote Host (Peer)

A remote host is another computer running AI Maestro that is connected to your mesh network.

Characteristics:

  • ✅ Distributes workload across multiple machines
  • ✅ Leverage different machine capabilities (Mac Mini for iOS builds, Linux server for Docker)
  • ✅ Scale horizontally (add more machines as needed)
  • ✅ Access dashboard from any connected peer
  • ⚠️ Requires network connectivity
  • ⚠️ Requires AI Maestro installed on each machine

Example:

Peer Mesh Network (All Connected as Equals)
  ├─ MacBook Pro → project-manager, code-reviewer
  ├─ Mac Mini → ios-build-agent, ui-tester
  └─ Cloud Server → database-migrations, deployment-agent

Access from any node - all see the same agents!

When to use:

  • Resource-intensive tasks (building large projects, running multiple LLMs)
  • Machine-specific requirements (Mac for iOS, Linux for Docker)
  • Team environments (share powerful machines)
  • Cost optimization (cheap cloud VMs for background tasks)

The Peer Mesh Network

AI Maestro uses a peer mesh architecture - all instances are equals, there's no central server.

Decentralized Design

Every AI Maestro instance is both a participant and a potential access point in the mesh.

Key Principles:

  • No hierarchy - Every node can discover and connect to other nodes
  • Bidirectional sync - Add a peer once, both sides auto-discover each other
  • Eventually consistent - All nodes converge to the same peer list
  • Access anywhere - Open the dashboard from any connected node

Analogy: Like BitTorrent or a decentralized network - no single point of failure.

How Peers Communicate

┌─────────────────────────────────────────────────────────────────┐
│  Your Browser (any node at :23000)                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Agent List                      Terminal View            │   │
│  │ ┌───────────────────┐          ┌────────────────────┐   │   │
│  │ │ MACBOOK-PRO       │          │ $ claude            │   │   │
│  │ │ ├─ project-mgr ●  │          │ > analyzing code... │   │   │
│  │ │ └─ code-review ●  │          │                     │   │   │
│  │ │                   │          │                     │   │   │
│  │ │ MAC-MINI          │          └────────────────────┘   │   │
│  │ │ ├─ ios-build ●    │                                    │   │
│  │ │ └─ ui-test ●      │                                    │   │
│  │ └───────────────────┘                                    │   │
│  └─────────────────────────────────────────────────────────┘   │
└──────────────────────────┬──────────────────────────────────────┘
                           │ WebSocket
                           ▼
            ┌──────────────────────────────┐
            │  Node A (MacBook Pro)        │
            │  Port 23000                  │
            │                              │
            │  ┌────────────────────────┐  │
            │  │ WebSocket Router       │  │
            │  │ - Local sessions       │  │
            │  │ - Proxy peer sessions  │  │
            │  └────────────────────────┘  │
            └──────┬────────────────┬──────┘
                   │                │
         ┌─────────▼─────┐   ┌─────▼──────────┐
         │ Local tmux    │   │ Peer Proxy     │
         │ sessions      │   │ (Mac Mini)     │
         └───────────────┘   └────────┬───────┘
                                      │ HTTP/WebSocket
                                      │ (Tailscale VPN)
                             ┌────────▼──────────┐
                             │ Node B (Mac Mini) │
                             │ Port 23000        │
                             │                   │
                             │ ┌───────────────┐ │
                             │ │ tmux sessions │ │
                             │ │ - ios-build   │ │
                             │ │ - ui-test     │ │
                             │ └───────────────┘ │
                             └───────────────────┘

Flow for Local Session:

  1. Browser connects via WebSocket to the node
  2. Node creates PTY directly to local tmux
  3. Terminal I/O flows: Browser ↔ Node ↔ Local tmux

Flow for Remote Peer Session:

  1. Browser connects via WebSocket to current node
  2. Node creates WebSocket to peer node
  3. Peer creates PTY to its local tmux
  4. Terminal I/O flows: Browser ↔ Node A ↔ Node B ↔ Remote tmux

Key Benefit: From the browser's perspective, all agents look the same - it doesn't care where they're running!

Automatic Peer Discovery

When you add a peer from any node:

Node A adds Node B
  │
  ├─► Node A calls: POST /api/hosts/register-peer to Node B
  │   (tells Node B about Node A)
  │
  ├─► Node A calls: POST /api/hosts/exchange-peers with Node B
  │   (shares peer lists)
  │
  └─► Both nodes now know about each other!
      New peers propagate to all connected nodes.

You only add once - the mesh takes care of the rest.

Agents and tmux Sessions

What is an Agent?

An agent is an AI coding assistant (like Claude Code, Aider, or Cursor) that you create and manage in AI Maestro.

Agent Anatomy:

Agent Name: customers-zoom-backend
  ├─ tmux session (terminal multiplexer - the underlying tool)
  ├─ Working directory: ~/projects/zoom-app/backend
  ├─ Claude Code instance (AI tool running inside)
  └─ Agent notes (stored in AI Maestro)

Hierarchical Organization

AI Maestro automatically organizes agents using a 3-level hierarchy based on naming:

Format: level1-level2-agentName

Example:

customers-zoom-backend
  └─ Level 1: "customers"     (top-level category)
  └─ Level 2: "zoom"          (subcategory/project)
  └─ Agent: "backend"         (specific agent)

Benefits:

  • Visual grouping in sidebar (collapsible folders)
  • Color-coded categories (auto-assigned)
  • Easy filtering by project or client
  • Scalable to hundreds of agents

Agent vs tmux Session

Important distinction:

  • Agent = What you create and manage (the AI assistant doing work)
  • tmux session = The underlying tool that runs the agent

When you create an agent, AI Maestro creates a tmux session for it. The tmux session is just the container - the agent is what matters to you.

Security Model

Understanding AI Maestro's security model helps you deploy it safely.

Localhost-Only Mode (Default)

Configuration:

// server.mjs
server.listen(23000, '0.0.0.0', () => { ... })

Security Characteristics:

  • ✅ Binds to all interfaces (0.0.0.0) but typically accessed via localhost
  • ✅ No authentication required (OS-level user security)
  • ✅ No encryption needed for localhost traffic
  • ⚠️ Accessible to other users on the same machine
  • ⚠️ Accessible to other devices if firewall allows

When secure:

  • Single-user machine (your personal MacBook)
  • Trusted network with firewall
  • No sensitive credentials in sessions

Tailscale VPN Mode (Recommended for Peers)

Configuration:

  • All nodes listen on 0.0.0.0:23000
  • Communication via Tailscale IPs (100.x.x.x)

Security Characteristics:

  • ✅ Encrypted tunnel (WireGuard protocol)
  • ✅ Private IP space (100.x.x.x)
  • ✅ NAT traversal (works behind firewalls)
  • ✅ Access control via Tailscale ACLs
  • ✅ No exposed ports to public internet

Setup:

  1. Install Tailscale on all machines
  2. Note Tailscale IPs (tailscale ip)
  3. Add peers using Tailscale IPs in Settings

When to use:

  • Remote machines (cloud servers, home lab)
  • Untrusted networks (coffee shop, coworking)
  • Team environments (share access securely)

Local Network Mode

Configuration:

  • Peers accessible via LAN IP (192.168.x.x)
  • Optional: .local domain (Bonjour/mDNS)

Security Characteristics:

  • ⚠️ Unencrypted traffic (unless you add HTTPS)
  • ⚠️ Accessible to anyone on network
  • ✅ Fast (no VPN overhead)
  • ✅ Simple (no VPN setup)

When to use:

  • Trusted home network
  • Isolated development network
  • Performance-critical scenarios (large file transfers)

What AI Maestro Does NOT Protect

AI Maestro assumes OS-level security:

  • ❌ No user authentication (anyone with access can control all agents)
  • ❌ No agent-level permissions (all agents visible to all users)
  • ❌ No credential encryption (don't store API keys in agent notes)
  • ❌ No audit logging (no record of who did what)

Best Practices:

  • Use OS user accounts to isolate users
  • Use environment variables for secrets (not hardcoded)
  • Use Tailscale ACLs to restrict network access
  • Use tmux access controls if needed

Key Takeaways

  1. Localhost = this machine, Remote Host = other machines in the mesh
  2. Peer mesh = all nodes are equal, no central server required
  3. Add once = bidirectional discovery syncs peers automatically
  4. Agents are automatically organized by naming convention (tmux sessions are the underlying tool)
  5. Security relies on OS users + network isolation (Tailscale recommended)
  6. Access the dashboard from any connected node - they all show the same agents

Next Steps: