Quickstart

Run Tanso and prove a five-credit hard limit end to end

Docker is the only prerequisite for the API. The runnable Next.js example also requires Node.js 20.9 or newer.

1. Start the stack

git clone https://github.com/tansohq/tanso-oss.git
cd tanso-oss/deploy
cp .env.example .env     # set JWT_SECRET, e.g. openssl rand -base64 48
docker compose up -d --build
./setup.sh

setup.sh waits for the API to become healthy, seeds a test account, and creates a demo-user with five AI_CREDITS:

Login:    test / password
API key:  sk_test_828df0fc77874c219f353417fbca1ef4
API:      http://localhost:8080
Docs:     http://localhost:8080/swagger-ui.html
Demo:     demo-user has 5 AI_CREDITS for feature ai.chat

These are the shared dev-quickstart credentials from scripts/create-test-account.sql. Change them before exposing the instance to anything real.

2. Run the working integration

From the repository root, in a second terminal:

npm install
cp examples/nextjs-ai-credits/.env.example \
  examples/nextjs-ai-credits/.env.local
npm run dev --workspace @tansohq/nextjs-ai-credits-example

Open http://localhost:3000. Run the request five times. Each successful call:

1. checks the entitlement before doing billable work;
2. runs a provider-free model stub;
3. records usage, cost, and revenue;
4. atomically deducts one credit.

The sixth call returns 402 from the example route before the provider stub runs. Event ingestion remains the final enforcement boundary and returns 409 Conflict if a caller races or skips the preflight check.

Read app/api/generate/route.ts for the complete check → work → record flow.

3. Open the admin console

The repo also ships a web console for the operator side of the same instance. From the repository root:

npm run dev:ui

Sign in with the seeded test / password login. The console prints its URL — http://localhost:3000, or the next free port if the example app is still holding 3000.

You’ll see the seeded catalog (the developer_demo plan and its ai.chat rule), the demo customer with its credit pool and transaction ledger, and every event the example just recorded — cost and revenue on each row. The console talks to the API through a same-origin proxy, so no CORS configuration is needed. Details in ui/README.md.

4. Verify the Client API

Client API calls authenticate with the API key, via either header:

curl "http://localhost:8080/api/v1/client/entitlements/demo-user/ai.chat?record=false" \
  -H "X-API-Key: sk_test_828df0fc77874c219f353417fbca1ef4"

{
  "data": {
    "referenceCustomerId": "demo-user",
    "featureKey": "ai.chat",
    "credit": {
      "denomination": "AI_CREDITS",
      "balance": 5,
      "hardLimit": true
    },
    "allowed": true
  },
  "success": true
}

Without the key, the same call returns 401. Re-run ./setup.sh to reset only the fixed demo customer’s five credits. The billing lifecycle guide shows how to create your own catalog and customer.

There is no signup endpoint

This is deliberate. A self-hosted billing engine’s operator is the tenant; a public signup endpoint on your billing system would be pure attack surface. You bootstrap your account with setup.sh (or scripts/create-test-account.sql directly) and log in from there.