Gateway

The Moxxy gateway is the background daemon that powers all agent operations.

What is the Gateway?

The gateway is a persistent background process that:

1. Manages Agents - Loads, initializes, and runs all configured agents
2. Serves the API - Provides the REST API for web, TUI, and external integrations
3. Connects Channels - Maintains connections to Telegram, Discord, Slack, WhatsApp
4. Executes Schedules - Runs cron-based autonomous tasks
5. Handles Webhooks - Processes incoming webhook requests

Lifecycle

┌─────────┐     ┌─────────┐     ┌─────────┐
│  start  │ ──▶ │ running │ ──▶ │  stop   │
└─────────┘     └─────────┘     └─────────┘
                    │
                    ▼
              ┌──────────┐
              │ restart  │
              └──────────┘

Commands

Start

moxxy gateway start

Initializes and starts the gateway daemon:

1. Creates run directory (~/.moxxy/run/)
2. Discovers all agents in ~/.moxxy/agents/
3. Boots each agent (loads persona, memory, skills)
4. Starts the API server (default: port 17890)
5. Connects configured channels
6. Begins schedule processing
7. Writes PID file

Stop

moxxy gateway stop

Gracefully shuts down the daemon:

1. Signals shutdown to all components
2. Waits for in-flight requests to complete
3. Saves agent state
4. Disconnects channels
5. Removes PID file

Restart

moxxy gateway restart

Equivalent to stop followed by start. Useful for:

• Reloading configuration
• Applying persona changes
• Refreshing channel connections

Status

moxxy gateway status

Displays current state:

● Gateway Status: Running
│
├─ PID:        12345
├─ Uptime:     2h 34m 12s
├─ API:        http://127.0.0.1:17890
├─ Agents:     3 active
│
└─ Channels:
   ├─ Telegram: @my_bot (connected)
   └─ Discord:  MyServer (connected)

Architecture

                    ┌──────────────────────┐
                    │    Gateway Daemon    │
                    └──────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌───────────────┐   ┌───────────────────┐   ┌──────────────┐
│  API Server   │   │ Channel Managers  │   │  Scheduler   │
│  (Axum/REST)  │   │ TG/DC/SLACK/WA    │   │  (Cron)      │
└───────────────┘   └───────────────────┘   └──────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   Agent Pool     │
                    │  ┌──┐ ┌──┐ ┌──┐  │
                    │  │A1│ │A2│ │A3│  │
                    │  └──┘ └──┘ └──┘  │
                    └──────────────────┘

Process Management

PID File

The gateway writes its process ID to:

~/.moxxy/run/moxxy.pid

This is used to:

• Check if the gateway is running
• Send signals to the process
• Prevent duplicate instances

Logs

Gateway logs are written to:

~/.moxxy/logs/gateway.log

View live logs:

moxxy logs

Auto-Restart (Optional)

For production deployments, use a process manager:

launchd (macOS):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.moxxy.gateway</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/moxxy</string>
        <string>gateway</string>
        <string>start</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

systemd (Linux):

[Unit]
Description=Moxxy Gateway
After=network.target

[Service]
Type=simple
User=youruser
ExecStart=/usr/local/bin/moxxy gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Configuration

Ports

Default ports can be customized in the vault:

# Set custom API port
moxxy run --agent default --prompt "Store 18900 in vault as gateway_port"

# Set custom web UI port  
moxxy run --agent default --prompt "Store 8080 in vault as web_ui_port"

Host Binding

By default, the gateway binds to 127.0.0.1. To expose externally:

moxxy run --agent default --prompt "Store 0.0.0.0 in vault as gateway_host"

WARNING

Binding to 0.0.0.0 exposes your API to the network. Ensure proper authentication and firewall rules.

Troubleshooting

Gateway Won't Start

1. Check for existing process:

   cat ~/.moxxy/run/moxxy.pid
   ps aux | grep moxxy

2. Remove stale PID file:

   rm ~/.moxxy/run/moxxy.pid

3. Check logs:

   cat ~/.moxxy/logs/gateway.log

Port Already in Use

# Find what's using the port
lsof -i :17890

# Kill the process or change the port

Agents Not Loading

Run diagnostics:

moxxy doctor

Check agent directories:

ls -la ~/.moxxy/agents/