Quickstart

Prerequisites

• Python 3.12+
• Redis (for background job processing)
• PostgreSQL (recommended) or SQLite
• 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/boxbilling.git
cd boxbilling/backend
uv sync

Step 2: Configure environment

cp .env.example .env

Edit .env with your settings:

APP_DOMAIN=localhost
APP_DATA_PATH=/var/lib/app
APP_DATABASE_DSN=postgresql://user:pass@localhost:5432/boxbilling
REDIS_URL=redis://localhost:6379

Tip

SQLite works for development — just use sqlite:///path/to/database.db as the 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.