Quickstart

Prerequisites

Python 3.12+
Redis (for background job processing)
PostgreSQL
UV package manager

Setup

Step 1: Install dependencies

# Install UV if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and install
git clone https://github.com/boxbilling/bxb.git
cd bxb/backend
uv sync

Step 2: Configure environment

cp .env.example .env

Edit .env with your settings:

BXB_APP_NAME=BoxBilling
BXB_DOMAIN=example.com
BXB_DATA_PATH=/var/lib/bxb
BXB_DATABASE_DSN=postgresql://user:pass@host:5432/database
BXB_WEBHOOK_SECRET=whsec_default_secret
BXB_CORS_ORIGINS=http://localhost:3000,http://localhost:5173
BXB_JWT_SECRET=
BXB_PORTAL_JWT_SECRET=portal-secret-change-me
BXB_RATE_LIMIT_EVENTS_PER_MINUTE=1000
BXB_ADMIN_SECRET=  # Secret for org creation/listing (X-Admin-Secret header)

REDIS_URL=redis://localhost:6379
OPENROUTER_API_KEY=
SENTRY_DSN=

Step 3: Run database migrations

alembic upgrade head

Step 4: Start the server

fastapi dev app/main.py

The API is now available at http://localhost:8000.

Step 5: Start the background worker

In a separate terminal:

arq app.worker.WorkerSettings

First API call

Create your organization and get an API key:

curl -X POST http://localhost:8000/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{"name": "My Company"}'

The response includes a raw_key — save this, it’s only shown once:

{
  "organization": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Company"
  },
  "raw_key": "bxb_live_abc123..."
}

Use this key for all subsequent requests:

curl http://localhost:8000/v1/customers \
  -H "Authorization: Bearer bxb_live_abc123..."

Docker

docker build -t boxbilling .
docker run -p 80:80 --env-file .env boxbilling

Next steps

Architecture Understand the system design.

API Reference Explore all API endpoints.

Subscriptions Set up your first subscription.

Usage billing Configure usage-based pricing.