Ravi

AI Maestro

What is AI Maestro?

AI Maestro is a web-based orchestration layer for AI coding agents. It runs at localhost:23000 and works with any terminal-based agent — Claude Code, Codex, Aider, Cursor, or custom scripts.

The core problem it solves: when you run dozens of agents, you become the human mailman shuttling context between them. AI Maestro eliminates that by giving agents a shared coordination layer.

Key capabilities:

  • Multi-machine peer mesh — agents on different computers appear in one dashboard. No central server; every node is equal.
  • Agent Messaging Protocol (AMP) — agents message each other directly with priority levels, typed message categories, and cryptographic signatures.
  • Gateways — connects to Slack, Discord, email, and WhatsApp, with prompt injection detection (34 patterns) at the gateway layer.
  • Persistent memory — conversation memory, an interactive code graph, and auto-generated documentation.
  • Kanban + war rooms — task coordination with split-pane workspaces for cross-agent collaboration.

AI Maestro solves the internal coordination problem well. When agents need to operate in the external world — signing up for services, verifying phone numbers, receiving confirmation emails — that requires real provisioned identity. That’s where Ravi fits.

Why Ravi

Real identity for each agent

AI Maestro has an “Agent Identity” feature: avatars and personality profiles for visual differentiation inside the dashboard. But external identity is different. When an agent registers for a service, it needs a real email address and phone number. Ravi provisions one per agent — each agent in your mesh gets its own @ravi.email address and phone number, ready to receive verification messages.

Credential isolation at scale

At 80+ agents, shared credentials create two problems: security and accountability. If Agent A’s GitHub token is available to Agent B’s environment, you lose both blast radius control and an audit trail. Ravi’s credential vault (passwords and secrets) lets each agent maintain isolated credentials. Access is scoped per identity.

Gateway-compatible inboxes

AI Maestro’s Gateways route messages into the agent mesh from external services. Ravi’s provisioned inboxes are the addresses agents give out when registering. Ravi handles receipt and parsing so agents can act on verification emails without human involvement — the full loop closes without you.

End-to-end auth flows

As agents autonomously log into services, two-factor authentication is the wall they hit. Ravi’s TOTP support means an agent can complete auth flows end-to-end, with no human in the loop for 2FA challenges.

Setup Guide

1. Install AI Maestro

npm install -g ai-maestro
ai-maestro start

The dashboard opens at http://localhost:23000.

2. Provision a Ravi identity per agent

Create a Ravi identity for each agent using the CLI. The --json flag outputs machine-readable identity details (uuid, email, phone) you can wire into your launch scripts.

# Create a Ravi identity for an agent (idempotent: || true handles already-exists)
ravi identity create --name "agent-alpha" --json 2>/dev/null || \
  ravi identity list --json | jq '.[] | select(.name == "agent-alpha")'

The response includes an inbox email address and phone number that belong exclusively to that agent.

3. Isolate each agent’s identity at launch

AI Maestro launches agents as separate processes. Use RAVI_CONFIG_DIR to scope each process to its own Ravi identity — this avoids the shared-state problem that comes from ravi identity use.

#!/usr/bin/env bash
# provision-and-launch.sh — run once per agent slot

AGENT_NAME="$1"    # e.g. "agent-alpha"
WORKSPACE="$HOME/.ai-maestro/workspaces/$AGENT_NAME"

mkdir -p "$WORKSPACE/.ravi"

# Create identity if it doesn't exist yet
IDENTITY=$(ravi identity create --name "$AGENT_NAME" --json 2>/dev/null || \
  ravi identity list --json | jq -c ".[] | select(.name == \"$AGENT_NAME\")")

IDENTITY_UUID=$(echo "$IDENTITY" | jq -r '.uuid')
AGENT_EMAIL=$(echo "$IDENTITY" | jq -r '.inbox')
AGENT_PHONE=$(echo "$IDENTITY" | jq -r '.phone')

# Write per-workspace config (RAVI_CONFIG_DIR picks this up automatically)
cat > "$WORKSPACE/.ravi/config.json" <<EOF
{"identity": "$IDENTITY_UUID"}
EOF

# Launch agent subprocess with isolated Ravi config
RAVI_CONFIG_DIR="$WORKSPACE/.ravi" \
AGENT_EMAIL="$AGENT_EMAIL" \
AGENT_PHONE="$AGENT_PHONE" \
  your-agent-binary --workspace "$WORKSPACE" --name "$AGENT_NAME"

Running 80 agents in parallel? Each gets its own RAVI_CONFIG_DIR. No race conditions.

4. Close the auth loop from agent code

When an agent triggers an auth flow (signup, 2FA, password reset), it polls its own Ravi inbox for the verification message and completes the flow without human involvement.

#!/usr/bin/env bash
# Inside an agent process — RAVI_CONFIG_DIR is already set in the environment

# 1. Get this agent's contact details
EMAIL=$(ravi get email --json | jq -r '.email')
PHONE=$(ravi get phone --json | jq -r '.phone_number')

# 2. Submit the form with the agent's real email/phone
# (browser automation or curl — tool-agnostic)

# 3. Poll for the OTP (retry loop, never bare sleep)
OTP=""
for i in $(seq 1 15); do
  OTP=$(ravi inbox sms --unread --json | jq -r '.[0].preview // empty')
  [ -n "$OTP" ] && break
  sleep 2
done
[ -z "$OTP" ] && { echo "OTP timeout after 30s" >&2; exit 1; }

# 4. Store credentials in this agent's vault
ravi passwords create example.com --username "$EMAIL" --json

5. Map Ravi inbound events to AMP

AI Maestro’s AMP can route external messages to the correct agent. You can bridge Ravi’s real-time SSE stream to AMP: subscribe to /api/events/stream/ (with X-Ravi-Identity: <uuid> and Authorization: Bearer <token>) and forward email and sms events as AMP messages to the owning agent’s context. See API Overview for the SSE event format.

Integration Pattern

The natural integration: when you register an agent in the AI Maestro dashboard, run provision-and-launch.sh to create its Ravi identity and write the per-workspace config. The dashboard can display each agent’s real-world identity (email, phone) alongside its coding workload — making AI Maestro the first orchestrator where agents are fully autonomous, not just in code execution but in external account access and service interaction.

Resources