Skip to main content

​
Self-Hosting Bossa

Run Bossa on your own infrastructure. For most users, the managed service is simpler — no Postgres, migrations, or deployment to manage. When self-hosting: CLI users must set BOSSA_API_URL to your deployment URL and SUPABASE_URL + SUPABASE_ANON_KEY (your Supabase project) so the CLI can authenticate.

​
Quick Start (Local)

One-liner (Postgres + migrations + seed + server): 
./scripts/run_local.sh
Or step by step:

​
1. Start Postgres

docker compose up -d postgres

​
2. Run migrations

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/001_initial_schema.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/002_workspace_api_keys.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/003_workspace_user_ownership.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/004_folders.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/005_usage_limits.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/006_tier_enum.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/007_schema_indexes.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/008_workspaces_user_fk.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/009_account_tiers_updated_at.sql

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/010_usage_daily_user_fk.sql

​
3. Start the server

cp .env.example .env        # ENV=development, DATABASE_URL pre-configured for local Docker
pip install -r requirements.txt
cd backend
uvicorn src.main:app --reload

​
4. Seed demo data

cd backend && python seed.py
Server is live at http://localhost:8000. Health at /health, MCP at /mcp, REST at /api/v1.

​
5. Run tests

pytest

​
Deploy to Supabase + Vercel

Hosted deployment path. API keys are required for all data endpoints (REST and MCP); only /health is public.

​
1. Create a Supabase project

Use the project Postgres connection string as DATABASE_URL. The app connects directly over Postgres, so no Supabase client setup is required.

​
2. Run migrations on Supabase

Apply all SQL migrations in order: 
supabase/migrations/001_initial_schema.sql
supabase/migrations/002_workspace_api_keys.sql
supabase/migrations/003_workspace_user_ownership.sql
supabase/migrations/004_folders.sql
supabase/migrations/005_usage_limits.sql
supabase/migrations/006_tier_enum.sql
supabase/migrations/007_schema_indexes.sql
supabase/migrations/008_workspaces_user_fk.sql
supabase/migrations/009_account_tiers_updated_at.sql
supabase/migrations/010_usage_daily_user_fk.sql
Run them with the Supabase SQL editor or psql against the Supabase Postgres endpoint.

​
3. Set Vercel environment variables

In your Vercel project settings, add: 
ENV=production
DATABASE_URL=postgres://postgres:[YOUR-PASSWORD]@db.[PROJECT-REF].supabase.co:6543/postgres
DEFAULT_WORKSPACE_ID=00000000-0000-0000-0000-000000000001
DEFAULT_API_KEY=sk-default
For CLI auth (signup/login) to work against your deployment: 
SUPABASE_URL=https://YOUR_PROJECT.supabase.co
SUPABASE_ANON_KEY=your-anon-key-from-supabase-dashboard
SUPABASE_JWT_SECRET=your-jwt-secret-from-supabase-dashboard
The CLI fetches SUPABASE_URL and SUPABASE_ANON_KEY from GET /auth/config when users point at your deployment. Users who self-host must set these env vars when running their own backend.

​
4. Deploy

vercel
For local Vercel-style verification: 
vercel dev

​
5. Smoke test

curl https://your-deployment-url.vercel.app/health
curl -H "Authorization: Bearer YOUR_API_KEY" https://your-deployment-url.vercel.app/api/v1/files/list?path=/
sk-default is blocked in production. Create keys with the CLI or python backend/scripts/create_workspace.py. MCP endpoint: https://your-deployment-url.vercel.app/mcp (pass Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY in client headers).

​
Usage limits

Tiers and limits are enforced via account_tiers and usage_daily (migrations 005, 006). To bypass limits for core developers, set OWNER_USER_IDS=uuid1,uuid2 (comma-separated user UUIDs). See Pricing & Limits for tier details.
Last modified on March 11, 2026