Gateway

The moxxy-gateway is the Rust binary that powers all agent operations, serving the REST API and managing the runtime.

What is the Gateway?

The gateway is a standalone Rust binary (built with Axum 0.8 and Tokio) that:

1. Serves the API - REST endpoints at /v1/ prefix on port 3000
2. Manages Agents - Creates, runs, and stops agents via the Executor
3. Connects Channels - Maintains Telegram and Discord bridges
4. Processes Events - Emits and persists 60 SSE event types with full audit logging
5. Runs Heartbeats - Executes scheduled heartbeat tasks on 1-minute ticks
6. Enforces Security - Sandbox profiles, allowlists, vault encryption, bearer token auth

Binary Management

The CLI (@moxxy/cli) auto-downloads the moxxy-gateway binary to:

~/.moxxy/bin/moxxy-gateway

The gateway is started and stopped through the CLI:

moxxy gateway start
moxxy gateway stop
moxxy gateway restart
moxxy gateway status

Startup Sequence

When the gateway starts, it performs these steps in order:

1. Load vault key - Checks MOXXY_VAULT_KEY env var, then ~/.moxxy/vault.key file, then generates a new key if neither exists
2. Open SQLite database - Opens ~/.moxxy/moxxy.db with WAL (Write-Ahead Logging) mode for concurrent reads
3. Register sqlite-vec - Loads the sqlite-vec extension for vector embedding operations
4. Spawn event persistence task - Background task that writes SSE events to the database
5. Spawn heartbeat scheduling loop - Ticks every 1 minute to fire due heartbeats
6. Spawn health check loop - Periodic health monitoring
7. Spawn drain/cleanup loop - Cleans up completed runs and expired data
8. Load channel bridges - Starts Telegram and Discord bots if configured
9. Start Axum server - Binds HTTP server with graceful shutdown support
10. Setup signal handlers - Listens for Ctrl+C and SIGTERM for clean shutdown

Architecture

                    +------------------------+
                    |    moxxy-gateway       |
                    |    (Rust / Axum 0.8)   |
                    +------------------------+
                              |
        +---------------------+---------------------+
        |                     |                     |
        v                     v                     v
+---------------+   +-------------------+   +--------------+
|  REST API     |   | Channel Bridges   |   |  Background  |
|  /v1/ prefix  |   | Telegram/Discord  |   |  Tasks       |
|  Port 3000    |   |                   |   |  Heartbeats  |
+---------------+   +-------------------+   |  Events      |
        |                     |             |  Health       |
        +---------------------+-------------+  Drain        |
                              |             +--------------+
                              v
                    +------------------+
                    |   moxxy.db       |
                    |   (SQLite WAL)   |
                    |   + sqlite-vec   |
                    +------------------+

Configuration

Port

Default: 3000. Override with:

export MOXXY_PORT=8080

Host Binding

Default: 127.0.0.1 (localhost only). Override with:

export MOXXY_HOST=0.0.0.0

WARNING

Binding to 0.0.0.0 exposes the API to the network. Ensure proper authentication and firewall rules are in place.

Database Path

Default: ~/.moxxy/moxxy.db. Override with:

export MOXXY_DB_PATH=/path/to/moxxy.db

CORS

Configure allowed origins:

export MOXXY_CORS_ORIGINS="http://localhost:3001,https://mydomain.com"

Rate Limiting

The gateway uses tower-governor for rate limiting. The default configuration is permissive, suitable for local development. Rate limits are configurable through the gateway's internal settings.

Authentication

All API requests require a bearer token (except the bootstrap endpoint for creating the first token):

curl -H "Authorization: Bearer mox_your_token_here" http://127.0.0.1:3000/v1/agents

Tokens use the mox_ prefix and are stored as SHA-256 hashes. Nine scopes control access:

Scope	Description
agents:read	Read agent information
agents:write	Create, update, delete agents
runs:write	Start and manage runs
vault:read	Read vault secrets
vault:write	Write vault secrets
tokens:admin	Manage API tokens
events:read	Read SSE event streams
channels:read	Read channel configuration
channels:write	Configure channels
*	All scopes

Loopback Mode

When MOXXY_LOOPBACK is set, requests from localhost bypass authentication. This is useful for local development.

Graceful Shutdown

The gateway handles shutdown signals (Ctrl+C, SIGTERM) gracefully:

1. Stops accepting new requests
2. Waits for in-flight requests to complete
3. Disconnects channel bridges
4. Flushes pending events to the database
5. Closes the SQLite connection
6. Exits cleanly

Data Directory

The gateway operates on the following directory structure:

~/.moxxy/
  moxxy.db          # Single SQLite database (WAL mode)
  vault.key         # Vault encryption key (AES-GCM)
  bin/
    moxxy-gateway   # The gateway binary
  config/           # Configuration files
  logs/             # Log files
  agents/
    {id}/
      workspace/    # Agent workspace (PathPolicy confined)
      memory/       # Markdown journals (append-only)
      config.yaml   # Agent configuration
      allowlist.yaml # Primitive allowlist/denylist

Process Management

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>~/.moxxy/bin/moxxy-gateway</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=%h/.moxxy/bin/moxxy-gateway
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Troubleshooting

Gateway Won't Start

1. Check if another process is using the port:

   lsof -i :3000

2. Verify the binary exists:

   ls -la ~/.moxxy/bin/moxxy-gateway

3. Check logs:

   cat ~/.moxxy/logs/gateway.log

Database Locked

SQLite WAL mode supports concurrent reads but only one writer. If you see "database is locked" errors, ensure only one gateway instance is running.

Channel Bridges Not Connecting

1. Verify channel tokens are stored in the vault
2. Check that the gateway has network access
3. Review logs for connection errors