Self-Hosting

Run Bossa on your own infrastructure. Docker, Supabase, Vercel.

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

docker compose exec -T postgres psql -U postgres -d bossa \
  -f - < supabase/migrations/011_enable_rls.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
supabase/migrations/011_enable_rls.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=/

Verify RLS (Supabase): anon key should return empty, not full data:

curl -H "apikey: $SUPABASE_ANON_KEY" "https://YOUR_PROJECT.supabase.co/rest/v1/files?select=id"
# Expected: [] or 401/403

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.