Gateway Setup¶

Detailed guide for deploying and configuring the Adaptive Sentience gateway.

Overview¶

The gateway is the central orchestrator that:

Routes workflow requests to edge nodes
Manages trust relationships
Provides HTTP and MCP APIs
Handles store-and-forward messaging
Collects observations and telemetry

Installation¶

Prerequisites¶

Python 3.9+
4GB+ RAM
Network connectivity
Linux, macOS, or Windows

Install from Source¶

# Clone repository
git clone https://github.com/adaptivesentience/agent_mesh.git
cd agent_mesh

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Verify Installation¶

python -m gateway.http_gateway --help

Configuration¶

Environment Variables¶

Create .env file:

# Gateway Configuration
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=8787
DEV_TOKEN_ENABLED=false

# Trust Configuration
TRUST_MODE=tofu  # or 'pki'
TRUST_STORE_PATH=trust/trust_store.json

# Node Identity
DWO_NODE_LAT=37.7749
DWO_NODE_LON=-122.4194
DWO_NODE_ACCURACY_M=50

# Mesh Transport
MESH_MULTICAST_IP=239.255.42.99
MESH_MULTICAST_PORT=9999

# Audit
AUDIT_LOG_PATH=audit/audit.log
AUDIT_LOG_LEVEL=INFO

# MCP Server (optional)
MCP_SERVER_PORT=8790
MCP_ENABLED=true

Command-Line Options¶

python -m gateway.http_gateway \
  --host 0.0.0.0 \
  --port 8787 \
  --dev-token \
  --trust-mode tofu \
  --identity gateway_identity.pem

Options:

--host: Bind address (default: 127.0.0.1)
--port: HTTP port (default: 8787)
--dev-token: Enable development token mode (insecure)
--trust-mode: Trust mode (tofu or pki)
--identity: Path to identity key file

Starting the Gateway¶

Development Mode¶

Quick start for testing:

cd agent_mesh

DWO_NODE_LAT=37.7749 DWO_NODE_LON=-122.4194 DWO_NODE_ACCURACY_M=50 \
  python -m gateway.http_gateway --host 127.0.0.1 --port 8787 --dev-token

Expected output:

============================================================
Gateway Starting
============================================================
Host: http://127.0.0.1:8787
Dev token: enabled
Trust mode: TOFU
Mesh transport: UDP multicast on 239.255.42.99:9999
============================================================
INFO:     Uvicorn running on http://127.0.0.1:8787 (Press CTRL+C to quit)

Production Mode¶

With PKI and proper configuration:

# Generate identity
python -m provisioning.generate_keys --output gateway_identity.pem

# Start gateway
python -m gateway.http_gateway \
  --host 0.0.0.0 \
  --port 8787 \
  --trust-mode pki \
  --identity gateway_identity.pem

Trust Configuration¶

TOFU Mode¶

Automatically trust nodes on first contact:

python -m gateway.http_gateway --trust-mode tofu

Use when: - Development/testing - Trusted network - Quick setup

PKI Mode¶

Explicit key exchange required:

# Generate gateway identity
python -m provisioning.generate_keys --output gateway_identity.pem

# Start gateway
python -m gateway.http_gateway \
  --trust-mode pki \
  --identity gateway_identity.pem

# Generate provisioning bundle for edge node
python -m provisioning.create_bundle \
  --gateway-key gateway_identity.pem \
  --node-id edge_node_1 \
  --output bundle.json

# Transfer bundle.json to edge node

Use when: - Production deployment - Untrusted network - Compliance requirements

API Endpoints¶

Health Check¶

curl http://127.0.0.1:8787/health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-01-27T10:30:00Z"
}

Tool Execution¶

curl -X POST http://127.0.0.1:8787/v1/tool/call \
  -H "Content-Type: application/json" \
  -d '{
    "target": {"kind": "local"},
    "tool_name": "pii_redact",
    "tool_args": {"text": "Contact john@example.com"}
  }'

Mesh Scan¶

curl http://127.0.0.1:8787/v1/mesh_scan | jq

Response:

{
  "nodes": [
    {
      "node_id": "local:abc123",
      "node_type": "macos",
      "http_url": "http://127.0.0.1:8000",
      "tools": ["pii_redact", "summarize"],
      "trust_status": "trusted",
      "last_seen": "2024-01-27T10:30:00Z"
    }
  ],
  "count": 1
}

Agent Discovery¶

curl http://127.0.0.1:8787/v1/agents | jq

MCP Server¶

Enable MCP integration for AI assistants:

# Start gateway with MCP server
python -m gateway.http_gateway \
  --host 127.0.0.1 \
  --port 8787 \
  --mcp-port 8790

Connect from Claude Desktop¶

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agent_mesh": {
      "command": "python",
      "args": ["-m", "gateway.mcp_server_cli", "--host", "127.0.0.1", "--port", "8790"]
    }
  }
}

Systemd Service (Linux)¶

Create Service File¶

sudo nano /etc/systemd/system/agent-mesh-gateway.service

[Unit]
Description=Adaptive Sentience Gateway
After=network.target

[Service]
Type=simple
User=agent-mesh
WorkingDirectory=/opt/agent_mesh
Environment="PATH=/opt/agent_mesh/venv/bin"
Environment="DWO_NODE_LAT=37.7749"
Environment="DWO_NODE_LON=-122.4194"
Environment="DWO_NODE_ACCURACY_M=50"
ExecStart=/opt/agent_mesh/venv/bin/python -m gateway.http_gateway --host 0.0.0.0 --port 8787
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start¶

sudo systemctl enable agent-mesh-gateway
sudo systemctl start agent-mesh-gateway
sudo systemctl status agent-mesh-gateway

# View logs
sudo journalctl -u agent-mesh-gateway -f

Docker Deployment¶

Dockerfile¶

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source
COPY . .

# Expose ports
EXPOSE 8787 8790

# Start gateway
CMD ["python", "-m", "gateway.http_gateway", "--host", "0.0.0.0", "--port", "8787"]

Build and Run¶

# Build image
docker build -t agent-mesh-gateway .

# Run container
docker run -d \
  --name gateway \
  -p 8787:8787 \
  -p 8790:8790 \
  -e DWO_NODE_LAT=37.7749 \
  -e DWO_NODE_LON=-122.4194 \
  -e DWO_NODE_ACCURACY_M=50 \
  agent-mesh-gateway

Monitoring¶

Health Checks¶

# Gateway health
curl http://127.0.0.1:8787/health

# Check if MCP server is running
curl http://127.0.0.1:8790/health

Metrics¶

# Gateway metrics
curl http://127.0.0.1:8787/v1/metrics | jq

# Example output
{
  "requests_total": 1523,
  "requests_success": 1498,
  "requests_failed": 25,
  "nodes_discovered": 4,
  "nodes_trusted": 3,
  "uptime_seconds": 86400
}

Logs¶

# View logs
tail -f gateway.log

# View audit log
tail -f audit/audit.log | jq

# Filter by workflow
cat audit/audit.log | jq 'select(.workflow_id == "feedback_safe_summary")'

Troubleshooting¶

Gateway Won't Start¶

Error: Address already in use

# Find process using port
lsof -i :8787

# Kill process
kill -9 <PID>

# Or use different port
python -m gateway.http_gateway --port 8788

Nodes Not Discovered¶

Problem: Gateway shows 0 nodes

Solutions:

Check multicast support:

# Test multicast
python -c "import socket; s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM); s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1); s.bind(('', 9999)); print('Multicast OK')"

Check firewall:
```
sudo ufw allow 9999/udp
```

Use manual node registration:

curl -X POST http://127.0.0.1:8787/v1/nodes/register \
  -d '{"node_id": "edge_1", "endpoint": "http://192.168.1.100:8000"}'

Trust Issues¶

Error: Node not trusted

# View trust store
cat trust/trust_store.json | jq

# Add node to trust store
curl -X POST http://127.0.0.1:8787/v1/trust/add \
  -d @bundle.json

Security Hardening¶

1. Disable Dev Token¶

Never use --dev-token in production:

# ❌ Insecure
python -m gateway.http_gateway --dev-token

# ✅ Secure
python -m gateway.http_gateway  # No dev token

2. Use TLS¶

Deploy behind reverse proxy with TLS:

server {
    listen 443 ssl;
    server_name gateway.example.com;

    ssl_certificate /etc/ssl/certs/gateway.crt;
    ssl_certificate_key /etc/ssl/private/gateway.key;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. Rate Limiting¶

limit_req_zone $binary_remote_addr zone=gateway:10m rate=10r/s;

server {
    location /v1/tool/call {
        limit_req zone=gateway burst=20;
        proxy_pass http://127.0.0.1:8787;
    }
}

4. Firewall Rules¶

# Allow only from known networks
sudo ufw allow from 192.168.1.0/24 to any port 8787

# Deny all others
sudo ufw default deny incoming

Next Steps¶

Edge Node Deployment - Deploy edge nodes
Android Deployment - Mobile setup
Architecture - Deployment architecture
API Reference - API documentation