Gradient Bang

Gradient Bang is an online multiplayer universe where you explore, trade, battle, and collaborate with other players and with LLMs. Everything in the game is an AI agent, including the ship you command.

The projects demonstrates the full capabilities of realtime agentic workflows, such as multi-tasking, advanced tool calling and low latency voice.

➡️ Join the play test

Table of Contents

1. Prerequisites
2. Quickstart
3. Running a game server
4. Running the bot
5. Deployment

Prerequisites

• uv: Python package manager
• Supabase Account: Game server functions, auth and database
• Docker: Required for local Supabase stack and agent deployment
• Node.js 18+: For edge function deployment and client
• (Optional) Pipecat Cloud Account: Production agent hosting
• (Optional) - Supabase CLI: If you cannot use npx, install the CLI globally instead

Quickstart

1. Create a new Supabase project

Note

You can do this via the Supabase Dashboard if preferred

npx supabase login

npx supabase projects create gb-game-server \
  --db-password some-secure-password \
  --region us-west-1 \
  --org-id my-org \
  --size small

Push config from /deployment/supabase template:

npx supabase config push --workdir deployment

2. Local dev setup

Note

Docker must be available and running on your system

Start Supabase locally

This may take some time on first run as required images are downloaded.

npx supabase start --workdir deployment/ 

Create .env.supabase in project root

Grab the required API keys:

npx supabase status -o env \
  --override-name auth.anon_key=SUPABASE_ANON_KEY \
  --override-name auth.service_role_key=SUPABASE_SERVICE_KEY \
  --workdir deployment

Copy the following into .env.supabase:

SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_ANON_KEY=eyJhbG...
SUPABASE_SERVICE_ROLE_KEY=eyJhbG...

# Edge function configuration
EDGE_API_TOKEN=your-random-token-here  # Generate: openssl rand -hex 32
EDGE_FUNCTIONS_URL=${SUPABASE_URL}/functions/v1

Optional: Run tests to validate setup

set -a && source .env.supabase && set +a

USE_SUPABASE_TESTS=1 uv run pytest tests/integration/ -v --supabase-dir deployment

If you run tests, be sure to clear database after

npx supabase db reset --workdir deployment

3. Generate world data / sector map

Run the universe bang script with number of sectors to chart and random seed

uv run universe-bang 5000 1234

This will create a world-data folder in the root of your project

Copy world data to local Supabase database

uv run -m gradientbang.scripts.load_universe_to_supabase --from-json world-data/

4. Create user account and character

Run Supabase edge functions process (leave running)

npx supabase functions serve --no-verify-jwt --workdir deployment --env-file .env.supabase

Create user account:

Option 1: Manually via Studio dashboard: http://127.0.0.1:54323/project/default/auth/users

Option 2: Via terminal:

curl -X POST http://127.0.0.1:54321/functions/v1/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secret123"
  }'

Verify Email:

Open Inbucket (local email viewer) and click confirmation link. Note: In local dev, the redirect URL will not be found.

open http://127.0.0.1:54324

Login and obtain access token:

curl -X POST http://127.0.0.1:54321/functions/v1/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "secret123"
  }'

Grab the access_token for the next steps!

Test Character Creation

Create a character (replace YOUR_ACCESS_TOKEN with the token from step 3):

curl -X POST http://127.0.0.1:54321/functions/v1/user_character_create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "name": "SpaceTrader"
  }'

5. Run the Pipecat agent and game client

Install Python dependencies:

uv sync --all-groups

Run agent process:

set -a && source .env.supabase && set +a

uv run bot

Run web client

With both your Supabase functions and Pipecat bot running, in a new terminal window:

cd client/

pnpm i
pnpm run dev

Deployment

Link remote Supabase project

npx supabase link --workdir deployment/

Create `.env.cloud environment

Note: these can be obtained via npx supabase projects api-keys

SUPABASE_URL=...
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
SUPABASE_DB_URL=...
EDGE_API_TOKEN=super-secret-prod-token
EDGE_FUNCTIONS_URL=...
EDGE_JWT_SECRET=super-secret-jwt-token-with-at-least-32-characters-long

Load env into terminal:

set -a && source .env.cloud && set +a

Push database

npx supabase db push --workdir deployment/ --linked

Add world data

uv run -m gradientbang.scripts.load_universe_to_supabase --from-json world-data/

Deploy edge functions

npx supabase functions deploy --workdir deployment/ --no-verify-jwt

Add required secrets

npx supabase secrets set --env-file .env.cloud

Note: we will need to add BOT_START_START_URL and BOT_START_API_KEY later

Deploy bot to Pipecat Cloud

Create .env.bot

DEEPGRAM_API_KEY=...
CARTESIA_API_KEY=...
GOOGLE_API_KEY=...
SUPABASE_URL=https://{SUPABASE_PROJECT_ID}.supabase.co
SUPABASE_SERVICE_ROLE_KEY=...
# Optional:
TOKEN_USAGE_LOG=logs/token_usage.csv
BOT_USE_KRISP=1

Create a new secret set on Pipecat Cloud:

pipecat cloud secrets set gb-bot-secrets --file .env.bot

Build and deploy bot

Note: create image pull credentials if publishing to a private repository

docker build -f deployment/Dockerfile.bot -t gb-bot:latest .
docker push gb-bot:latest

cd deployment/
pipecat cloud deploy 
# ... or if public
# pipecat cloud deploy --no-credentials

Update edge functions with API Key and Start URL

Create and note down Public API Key

pipecat cloud organizations keys create

Update .env.cloud with additional bot envs:

SUPABASE_URL=...
SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...
SUPABASE_DB_URL=...
EDGE_API_TOKEN=...
EDGE_FUNCTIONS_URL=...
EDGE_JWT_SECRET=...
# Add these
BOT_START_URL=https://api.pipecat.daily.co/v1/public/{AGENT_NAME}/start
BOT_START_API_KEY=...

Apply to edge functions

npx supabase secrets set --env-file .env.cloud

Point client to your production environment

touch client/app/.env

VITE_SERVER_URL=https://{SUPABASE_PROJECT_ID}.supabase.co/functions/v1
VITE_PIPECAT_TRANSPORT=daily

Run the client

cd client/

pnpm run dev