ClawXP

Quick Start

This guide walks through running ClawXP locally and connecting your first client.

Prerequisites

  • Go 1.22+: Install Go
  • Node.js 18+: Install Node
  • pnpm: npm install -g pnpm
  • mkcert: For local TLS certificates (required for WebTransport)

1. Generate TLS Certificates

WebTransport requires TLS. Use mkcert for local development:

# Install mkcert
brew install mkcert  # macOS
# or see https://github.com/FiloSottile/mkcert for other platforms

# Install local CA
mkcert -install

# Generate certificates
mkdir -p infra/certs
mkcert -key-file infra/certs/key.pem -cert-file infra/certs/cert.pem localhost 127.0.0.1 ::1

2. Start Redis (Optional)

For single-instance development, ClawXP uses an in-memory adapter. For multi-instance or production, use Redis:

docker-compose -f infra/docker-compose.yml up -d redis

3. Start the Server

cd server

# Set environment variables
export TLS_CERT_FILE=../infra/certs/cert.pem
export TLS_KEY_FILE=../infra/certs/key.pem
export AUTH_DEV_TOKEN=devtoken

# Run the server
go run cmd/ClawXPd/main.go

The server starts on:

  • WebTransport: https://localhost:8443/wt
  • WebSocket: wss://localhost:8443/ws
  • Metrics: http://localhost:8080/metrics

4. Connect a Client

Install the SDK:

pnpm add @clawxp/sdk

Create a client:

import { ClawXPClient, SubscriptionMode } from '@clawxp/sdk';

const client = new ClawXPClient({
  url: 'https://localhost:8443',
  token: 'devtoken',
  fallback: true,
});

await client.connect();

// Subscribe to a channel
const sub = await client.subscribe('prices:SOL/USDC', {
  mode: SubscriptionMode.DATAGRAM,
});

sub.onMessage((msg) => {
  console.log('Price update:', msg.data);
});

// Publish a message
await client.publish('prices:SOL/USDC', {
  price: 123.45,
  timestamp: Date.now(),
});

5. Check Metrics

Visit http://localhost:8080/metrics to see Prometheus metrics including:

  • ClawXP_connections_total
  • ClawXP_subscriptions
  • ClawXP_publishes_total
  • ClawXP_datagrams_sent_total

Next Steps