Skip to content

Quick Start

Tessera is a USDC support sidecar. Run it locally, then point your platform plugin at it.

1. Prerequisites

  • Node.js 22 or higher (CI and the Docker image use 22)
  • Git
  • Circle Developer account: CIRCLE_API_KEY (API key) and CIRCLE_APP_ID (App ID)

Docker is optional. The repo includes a Dockerfile (port 7878, data volume /app/data).

2. Installation

git clone https://github.com/JaDi03/tessera.git
cd tessera
npm install
cp .env.example .env

Configure environment variables

Edit .env. Required:

  • CIRCLE_API_KEY
  • CIRCLE_APP_ID
  • MASTER_KEY (32+ random characters)
  • TESSERA_INGEST_SECRET (same value in your platform plugin; Tessera exits on start if this is missing)

Optional: PUBLIC_URL, PORT (default 7878), ARC_RPC_URL, CIRCLE_GOOGLE_CLIENT_ID. Full list: .env.example.

npm run build
npm start

The process listens on 0.0.0.0 and logs Tessera running on http://localhost:7878 (or your PORT). Check:

curl -sS http://127.0.0.1:7878/health

3. Tessera Base URL

The Tessera Base URL is the origin the plugin server uses to POST sessions/start and sessions/stop (scheme + host + port). Put the same TESSERA_INGEST_SECRET in the plugin.

Where Tessera and the platform run Base URL
Same machine, no containers http://127.0.0.1: + Tessera port (default 7878)
Platform in a container, Tessera on the host Host address as seen from the container (often http://172.17.0.1: + port on Docker's default bridge). Confirm with the check below.
Both in containers on the same Docker network http:// + Tessera service name + : + port
Tessera on its own domain That HTTPS origin

Verify from the host or container that runs the plugin:

curl -sS http://HOST:PORT/health

If that succeeds, that origin is the Base URL.

Viewers load the overlay from the plugin relay on the platform origin, or from {sidecar}/assets/. HMAC contract: Connector spec.

4. Docker deploy

deploy.sh rebuilds the image and restarts the container. From the repo root, with Docker and a filled .env:

./deploy.sh
# or: ./deploy.sh main

The script:

  1. git fetch origin and git reset --hard origin/<branch> (main if you omit the argument)
  2. docker build --no-cache -t tessera-backend .
  3. Recreates container tessera-backend: -p 7878:7878, --env-file .env, volume ./data → /app/data, network tessera_net, --restart unless-stopped

On that Docker network the plugin Base URL is http://tessera-backend:7878. Confirm with GET /health.

5. Next