Skip to main content

Quick Start

Get the Clutch Protocol stack running in minutes.

Prerequisites​

  • Docker and Docker Compose
  • Node.js 20+ (only if running demo app outside Docker)
  • (Optional) GHCR login: docker login ghcr.io — see Docker images for package links

1. Clone and start full stack​

git clone https://github.com/clutchprotocol/clutch-deploy.git
cd clutch-deploy

cp .env.example .env

.env.example ships a placeholder JWT_SECRET, and the Hub API refuses to start on an empty, placeholder, or shorter-than-32-character secret — so generate a real one:

# PowerShell
$bytes = New-Object byte[] 32
[System.Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
($bytes | ForEach-Object { $_.ToString('x2') }) -join ''
# bash
openssl rand -hex 32

Replace the JWT_SECRET=your-super-secret-jwt-key-here line in .env with the generated value:

JWT_SECRET=<paste the 64-character value here>

The remaining values in .env.example start the stack as shipped. Now bring it up:

docker compose up -d

This starts nodes, Hub API, demo app, explorer, Prometheus, Grafana, and Seq.

2. Verify services​

ServiceURL
API healthhttp://localhost:3000/health
GraphQLhttp://localhost:3000/graphql
Demo apphttp://localhost:5173
Explorerhttp://localhost:5174
Grafanahttp://localhost:3030 (admin / GRAFANA_ADMIN_PASSWORD from .env)
Seq logshttp://localhost:5341 (SEQ_ADMIN_USERNAME / SEQ_ADMIN_PASSWORD from .env)

3. Try the demo app​

Open http://localhost:5173:

  1. Choose Passenger or Driver
  2. Connect your wallet (MetaMask, Trust Wallet or TronLink; the app holds no key)
  3. Fund the wallet: ☰ → Wallet → Top up, then send USDT (TRC-20) to the address shown — see Deposits
  4. As passenger: pick locations on the map and request a ride
  5. As driver: view requests and submit an offer

Or run the demo from the clutch-hub repo:

git clone https://github.com/clutchprotocol/clutch-hub.git
cd clutch-hub
npm install
VITE_API_URL=http://localhost:3000 npm run dev

4. Build with the SDK​

npm install clutch-hub-sdk-js
import { ClutchHubSdk } from 'clutch-hub-sdk-js';

const sdk = new ClutchHubSdk('http://localhost:3000', publicKey);

const balance = await sdk.getAccountBalance(); // bigint

Fund the wallet first — see Deposits.

See Ride Lifecycle for the full flow.

Next steps​