GUIDE

Navigate to your trusted folder (the one configured in the Sandbox) and run:

cd ~/Documents/Projects
fararoni --server

Startup Output

First the server mode banner:

╔═══════════════════════════════════════════════════════════════╗
║           FARARONI SERVER - IDE Plugin Mode                    ║
╚═══════════════════════════════════════════════════════════════╝

[SERVER] Initializing components...

Then Fararoni loads all subsystems:

[FARARONI] Primary link stable.
[FARARONI]  Armored Persistence ACTIVE (Outbox Pattern: sovereign_bus.db)
[FARARONI]  Channel repository initialized
[FARARONI]  MessagingChannelManager started
[FARARONI]  Security Auth ACTIVE (TOTP + Sandbox + BCrypt)
[FARARONI]  GalvanicAgent started on Sovereign Bus
[FARARONI]  QuartermasterAgent started on Sovereign Bus
[FARARONI]  AgentTemplateManager started (10 active agents, LLM injected)
[FARARONI]  SovereignMissionEngine active
[RECOVERY] Disaster Recovery Service started
[SAFETY] FileSystemIntentListener active (Write + Restore)
[TOOL-REGISTRY] Base tools: 36+
 Dynamic Tool Prompting enabled

When everything is ready, the panel with available endpoints appears:

╔═══════════════════════════════════════════════════════════════╗
║  [ACTIVE] SERVER ACTIVE                                       ║
╠═══════════════════════════════════════════════════════════════╣
║  Base URL:    http://localhost:7070                            ║
║                                                               ║
║  REST Endpoints:                                              ║
║    POST   /api/chat           - Synchronous chat (IDE)        ║
║    POST   /api/task           - Execute mission (async)       ║
║    GET    /api/status         - Server status                 ║
║    GET    /api/session/{id}   - Session status                ║
║    DELETE /api/session/{id}   - Close session                 ║
║    GET    /health             - Health check                  ║
║                                                               ║
║  WebSocket:                                                   ║
║    WS     /ws/events?userId=X - Live event feed               ║
║                                                               ║
║  Press CTRL+C to stop the server                              ║
╚═══════════════════════════════════════════════════════════════╝

The server runs in the foreground. Do not close this terminal while using Fararoni in server mode.

Open a new terminal and run:

# Core Server health check
curl http://localhost:7070/health
# {"status":"healthy"}

# Server status
curl http://localhost:7070/api/status

# Gateway health check
curl http://localhost:7071/gateway/v1/health
# {"status":"healthy","port":7071,"activeClients":0}

When starting with --server, Fararoni starts two services:

The Gateway starts automatically — no need to start it separately.

With the server running, open a new terminal for each channel you want to activate.

WhatsApp

# Terminal 2
~/Fararoni/bin/sidecar-whatsapp

A QR code will appear in the terminal. Scan it with WhatsApp: Settings → Linked Devices → Link a Device.

Telegram

Requires a token from @BotFather:

# Terminal 3
export TELEGRAM_TOKEN="your_botfather_token"
~/Fararoni/bin/sidecar-telegram

Discord

Requires a token from the Discord Developer Portal:

# Terminal 4
export DISCORD_TOKEN="your_developer_portal_token"
~/Fararoni/bin/sidecar-discord

iMessage (macOS only)

Requires BlueBubbles running on your Mac:

# Terminal 5
export BLUEBUBBLES_PASSWORD="your_password"
~/Fararoni/bin/sidecar-imessage

# WhatsApp (port 3000)
curl http://localhost:3000/health

# Telegram (port 3001)
curl http://localhost:3001/health

# Discord (port 3002)
curl http://localhost:3002/health

# iMessage (port 3003)
curl http://localhost:3003/health

Each health check returns the channel connection status:

{"status":"healthy","connection":"connected","channelId":"telegram","port":3001}

User (WhatsApp/Telegram/Discord/iMessage)
        |
        v
Sidecar (native binary, port 3000-3003)
        |
        v  POST /gateway/v1/inbound
OmniChannel Gateway (:7071)
        |
        v
SovereignEventBus
        |
        v
Fararoni Core (:7070) — processes with LLM
        |
        v  POST /send
SovereignEventBus → HttpEgressDispatcher
        |
        v
Sidecar → User

Verified Real Example (Telegram)

[INFO]  13:18:39 [HTTP] Egress Server on port 3001
[INFO]  13:18:40 [INGRESS] 1568104683 -> "Hello" (HTTP 202)
[INFO]  13:18:48 [EGRESS] 1568104683 <- "Hello! How can I help you today?"

Synchronous Chat (for IDE plugins)

curl -X POST http://localhost:7070/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "analyze this project", "userId": "ide-user"}'

Execute Async Mission

curl -X POST http://localhost:7070/api/task \
  -H "Content-Type: application/json" \
  -d '{"task": "create a payments microservice", "userId": "user1"}'

Server Status

curl http://localhost:7070/api/status

WebSocket (live feed)

Connect to ws://localhost:7070/ws/events?userId=your-user to receive real-time events (LLM responses, mission progress, etc.).

Press Ctrl+C in the terminal where the server is running. This stops both the Core and Gateway.

To stop sidecars, press Ctrl+C in each terminal, or if registered as LaunchAgents:

launchctl unload ~/Library/LaunchAgents/com.fararoni.sidecar-*.plist
launchctl unload ~/Library/LaunchAgents/com.fararoni.core.plist

Fararoni v1.0.0 — Sovereign AI Agent Orchestrator | Apache 2.0 | Author: Eber Cruz