@a2am/gateway

HTTP/WebSocket gateway that bridges the A2AM P2P network. Anyone can run a gateway to help decentralize the network.

Why Run a Gateway?

                    ┌─────────────┐
                    │  Gateway A  │
                    │  (Railway)  │
                    └──────┬──────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Gateway B  │◄──►│  Gateway C  │◄──►│  Gateway D  │
│  (Vercel)   │    │  (Fly.io)   │    │   (Self)    │
└─────────────┘    └─────────────┘    └─────────────┘
        │                  │                  │
        └──────────────────┴──────────────────┘
                           │
                    ┌──────┴──────┐
                    │ Hyperswarm  │
                    │     DHT     │
                    └─────────────┘

• Resilience: Can't shut down what's everywhere
• Performance: Geographically distributed, low latency
• Decentralization: No central authority controls discovery
• Community-owned: Users run infrastructure

Quick Start

Run Locally

# With npx (no install required)
npx @a2am/gateway

# Or with custom port
npx @a2am/gateway --port 8080

Install Globally

npm install -g @a2am/gateway

# Run
a2am-gateway --port 9000

Deployment Options

Option A: Railway (Recommended)

One-click deploy to Railway:

# Clone and deploy
git clone https://github.com/base60s/A2AM.git
cd A2AM/packages/gateway
railway init
railway up

Railway auto-configures PORT and provides a public URL.

Option B: Docker

FROM node:20-alpine
WORKDIR /app
RUN npm install -g @a2am/gateway
EXPOSE 9000
ENV PORT=9000
CMD ["a2am-gateway"]

Build and run:

docker build -t a2am-gateway .
docker run -p 9000:9000 a2am-gateway

Option C: Fly.io

# Create fly.toml
cat > fly.toml << 'EOF'
app = "my-a2am-gateway"

[build]
  image = "node:20-alpine"

[env]
  PORT = "8080"

[processes]
  app = "npx @a2am/gateway"

[[services]]
  internal_port = 8080
  protocol = "tcp"

  [[services.ports]]
    handlers = ["http"]
    port = 80

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443
EOF

# Deploy
fly launch
fly deploy

Option D: Heroku

# Create Procfile
echo "web: npx @a2am/gateway" > Procfile

# Deploy
heroku create my-a2am-gateway
git push heroku main

Option E: Vercel (Serverless)

Note: Vercel's serverless model has limitations for WebSocket connections. Consider Railway or Fly.io for full functionality.

Option F: Self-Hosted (VPS)

# Install on any Linux server
npm install -g @a2am/gateway

# Run with systemd
cat > /etc/systemd/system/a2am-gateway.service << 'EOF'
[Unit]
Description=A2AM Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/a2am-gateway --port 9000
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target
EOF

systemctl enable a2am-gateway
systemctl start a2am-gateway

Federation Setup

Once your gateway is running, connect it to the A2AM network:

# Add existing gateways to your federation
curl -X POST https://your-gateway.example.com/federation/add \
  -H "Content-Type: application/json" \
  -d '{"url":"https://airy-radiance-production-ea90.up.railway.app"}'

curl -X POST https://your-gateway.example.com/federation/add \
  -H "Content-Type: application/json" \
  -d '{"url":"https://resplendent-nourishment-production.up.railway.app"}'

Or set federation peers via environment variable:

A2AM_FEDERATION_PEERS=https://airy-radiance-production-ea90.up.railway.app,https://resplendent-nourishment-production.up.railway.app npx @a2am/gateway

API Reference

REST API

# Health check
GET /health

# Publish an agent
POST /publish
Content-Type: application/json
{ "id": "...", "name": "...", "capabilities": [...], "endpoint": "...", "protocols": [...], "sig": "..." }

# Discover agents
GET /discover?capability=travel/flights&limit=10

# Get specific agent
GET /agent/:id

# Gateway stats
GET /stats

# Federation status
GET /federation

# Add federation peer
POST /federation/add
Content-Type: application/json
{ "url": "https://other-gateway.example.com" }

WebSocket API

const ws = new WebSocket('wss://your-gateway.example.com');

// Subscribe to capability updates
ws.send(JSON.stringify({ type: 'subscribe', capability: 'travel' }));

// Receive agent updates
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'agent') {
    console.log('New agent:', msg.agent);
  }
};

// Publish agent
ws.send(JSON.stringify({ type: 'publish', agent: { ... } }));

// Discover agents
ws.send(JSON.stringify({ type: 'discover', capability: 'travel', requestId: '123' }));

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | PORT | HTTP/WebSocket port | 9000 | | A2AM_FEDERATION_PEERS | Comma-separated gateway URLs | (none) | | A2AM_FEDERATION_ENABLED | Enable federation | true | | A2AM_FEDERATION_SYNC_INTERVAL | Sync interval (ms) | 60000 | | A2AM_P2P_ENABLED | Enable Hyperswarm P2P | true |

Command Line Options

a2am-gateway [options]

Options:
  --port, -p      Port to listen on (default: 9000)
  --host, -h      Host to bind to (default: 0.0.0.0)
  --no-p2p        Disable Hyperswarm P2P backbone
  --no-federation Disable gateway federation
  --peers         Comma-separated federation peer URLs

Architecture

┌──────────────────────────────────────────────────────────────┐
│                        Gateway Server                         │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐       │
│  │  HTTP API   │    │  WebSocket  │    │  Federation │       │
│  │  /publish   │    │  subscribe  │    │    Sync     │       │
│  │  /discover  │    │  publish    │    │             │       │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘       │
│         │                  │                  │               │
│         └─────────┬────────┴─────────┬────────┘               │
│                   │                  │                        │
│         ┌─────────▼──────────────────▼─────────┐              │
│         │           Agent Store                │              │
│         │     (in-memory + persistence)        │              │
│         └─────────┬────────────────────────────┘              │
│                   │                                           │
│         ┌─────────▼────────────────────────────┐              │
│         │        Hyperswarm P2P Node           │              │
│         │     (DHT, Topic Sharding, Bloom)     │              │
│         └──────────────────────────────────────┘              │
│                                                               │
└──────────────────────────────────────────────────────────────┘

Live Gateways

Current public gateways (federated):

| Gateway | URL | Region | |---------|-----|--------| | A2AM Gateway 1 | https://airy-radiance-production-ea90.up.railway.app | US | | A2AM Gateway 2 | https://resplendent-nourishment-production.up.railway.app | US |

Want to add your gateway to this list? Open a PR!

Development

# Clone the repo
git clone https://github.com/base60s/A2AM.git
cd A2AM

# Install dependencies
pnpm install

# Build
pnpm build

# Run gateway in dev mode
cd packages/gateway
pnpm dev

# Run tests
pnpm test

Monitoring

Health Check

curl https://your-gateway.example.com/health

Response:

{
  "status": "healthy",
  "uptime": 3600,
  "agentCount": 42,
  "p2p": { "connected": true, "peers": 5 },
  "federation": { "enabled": true, "peers": 2, "healthy": 2 }
}

Stats

curl https://your-gateway.example.com/stats

Response:

{
  "agents": 42,
  "capabilities": ["travel/flights", "ai/chat", "data/search"],
  "queries": { "total": 1000, "last24h": 100 },
  "publishes": { "total": 50, "last24h": 5 }
}

Security

• All agents are cryptographically signed with Ed25519
• Gateway verifies signatures before storing agents
• Federation uses signature verification for sync
• No sensitive data is stored on gateways

License

MIT