Gateway Configuration

Configure the HTTP webhook gateway and tunnel services

The gateway enables HTTP webhooks for external integrations. Configure the server, pairing flow, and optional tunnel providers.

Basic Gateway Configuration

{
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "allow_public_bind": false,
    "pair_rate_limit_per_minute": 10,
    "webhook_rate_limit_per_minute": 60,
    "idempotency_ttl_secs": 300,
    "paired_tokens": []
  }
}

gateway.port · number · default: "3000"

Port to bind the HTTP server to.

gateway.host · string · default: "127.0.0.1"

Host address to bind to. Use 127.0.0.1 (localhost) for local-only access, or 0.0.0.0 to allow external connections.

gateway.require_pairing · boolean · default: "true"

Require clients to complete pairing flow before sending webhooks. Highly recommended.

gateway.allow_public_bind · boolean · default: "false"

Allow binding to 0.0.0.0 (all interfaces). Must be explicitly enabled for security.

Setting allow_public_bind: true exposes the gateway to your network. Always use require_pairing: true and configure firewall rules.

Pairing Flow

The pairing flow authenticates external clients:

1. Client requests pairing code: POST /pair/request
2. NullClaw displays pairing code to the user
3. User approves pairing
4. Client exchanges code for token: POST /pair/confirm
5. Client uses token in Authorization: Bearer <token> header for all requests

Pairing Configuration

gateway.pair_rate_limit_per_minute · number · default: "10"

Rate limit for pairing requests (per IP address).

gateway.webhook_rate_limit_per_minute · number · default: "60"

Rate limit for webhook requests (per token).

gateway.idempotency_ttl_secs · number · default: "300"

TTL for idempotency keys (prevents duplicate webhook processing).

gateway.paired_tokens · array

Pre-authorized bearer tokens (bypasses pairing flow). Use for service-to-service integration.

Example: Pre-authorized Token

{
  "gateway": {
    "require_pairing": true,
    "paired_tokens": [
      "service-token-abc123"
    ]
  }
}

Clients can use Authorization: Bearer service-token-abc123 without pairing.

Tunnel Configuration

Tunnels expose the local gateway to the public internet:

{
  "tunnel": {
    "provider": "cloudflared"
  }
}

tunnel.provider · string · default: "none"

Tunnel provider:

• none — No tunnel (default)
• cloudflared — Cloudflare Tunnel
• ngrok — Ngrok tunnel
• tailscale — Tailscale Funnel
• custom — Custom tunnel command

Cloudflare Tunnel

Automatic HTTPS tunnel via Cloudflare:

{
  "tunnel": {
    "provider": "cloudflared"
  },
  "gateway": {
    "port": 3000,
    "require_pairing": true
  }
}

Setup:

1. Install cloudflared: Download
2. Run NullClaw with tunnel enabled:
   nullclaw listen
   
3. NullClaw will print the public HTTPS URL

Ngrok Tunnel

Expose via ngrok:

{
  "tunnel": {
    "provider": "ngrok"
  },
  "gateway": {
    "port": 3000
  }
}

Setup:

1. Install ngrok: Download
2. Set auth token: ngrok authtoken <your-token>
3. Run NullClaw:
   nullclaw listen
   

Tailscale Funnel

Expose via Tailscale:

{
  "tunnel": {
    "provider": "tailscale"
  },
  "gateway": {
    "port": 3000
  }
}

Setup:

1. Install Tailscale: Download
2. Enable Funnel: tailscale funnel on
3. Run NullClaw

Webhook Endpoints

The gateway exposes these endpoints:

POST /pair/request

Request a pairing code.

Response:

{
  "code": "ABCD1234",
  "expires_at": "2026-03-01T15:30:00Z"
}

POST /pair/confirm

Exchange pairing code for token.

Request:

{
  "code": "ABCD1234"
}

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": "2026-04-01T15:30:00Z"
}

POST /webhook

Send a message to NullClaw.

Headers:

Authorization: Bearer <token>
Content-Type: application/json
X-Idempotency-Key: unique-request-id

Request:

{
  "message": "What's the weather today?",
  "session_id": "optional-session-id",
  "metadata": {
    "source": "external-service"
  }
}

Response:

{
  "response": "I can't check the weather directly, but you can...",
  "session_id": "session-abc123"
}

GET /health

Health check endpoint (no auth required).

Response:

{
  "status": "ok",
  "version": "0.1.0"
}

Example: Public Gateway with Tunnel

{
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "pair_rate_limit_per_minute": 5,
    "webhook_rate_limit_per_minute": 30
  },
  "tunnel": {
    "provider": "cloudflared"
  }
}

This configuration:

• Binds gateway to localhost (secure)
• Requires pairing for all clients
• Exposes via Cloudflare Tunnel (automatic HTTPS)
• Rate limits pairing and webhook requests

Example: Service Integration

{
  "gateway": {
    "port": 3000,
    "host": "127.0.0.1",
    "require_pairing": true,
    "paired_tokens": [
      "service-token-production-xyz"
    ]
  }
}

Use for service-to-service integration:

curl -X POST http://localhost:3000/webhook \
  -H "Authorization: Bearer service-token-production-xyz" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: request-$(date +%s)" \
  -d '{
    "message": "Analyze the latest error logs",
    "session_id": "monitoring-service"
  }'

Security Best Practices

Always enable require_pairing

Pairing flow prevents unauthorized access. Only disable if using paired_tokens for service accounts.

Use localhost by default

Bind to 127.0.0.1 (localhost) unless you need external access. Use tunnels for internet exposure.

Rate limit aggressively

Set conservative rate limits to prevent abuse:

• pair_rate_limit_per_minute: 5 (pairing is rare)
• webhook_rate_limit_per_minute: 30 (adjust based on usage)

Use idempotency keys

Always send X-Idempotency-Key header to prevent duplicate processing of webhooks.

Rotate paired tokens

Pre-authorized tokens in paired_tokens don’t expire. Rotate them periodically.

The gateway uses HTTPS when accessed via tunnels (cloudflared, ngrok, tailscale). Local access uses HTTP.