Skip to main content

​
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
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.