Quickstart

Get Airbeeps up and running in 5 minutes.

Requirements

• Python 3.13+ with uv (recommended) or pip
• Node.js 20+ with pnpm (for development mode)

Option 1: Install from PyPI

The fastest way to get started:

pip install airbeeps
airbeeps run

Open http://localhost:8500 and sign up. The first registered user automatically becomes an admin.

The airbeeps run command automatically:

1. Runs database migrations (if needed)
2. Seeds default configuration data (on first run)
3. Starts the FastAPI server with bundled frontend

Option 2: Docker (production)

For production deployments with PostgreSQL, Redis, Qdrant, and MinIO:

git clone https://github.com/airbeeps/airbeeps.git
cd airbeeps
cp .env.docker.example .env
# Edit .env with your secrets
docker compose up -d

Open http://localhost:8080 and sign up.

See Docker Deployment for the full guide.

Option 3: Development setup

For contributors or those who want to modify the source:

1. Clone the repository

git clone https://github.com/airbeeps/airbeeps.git
cd airbeeps

2. Set up the backend

cd backend
cp .env.example .env

Generate a secret key and add it to .env:

Linux/macOS:

echo "AIRBEEPS_SECRET_KEY=$(openssl rand -hex 32)" >> .env

Windows PowerShell:

"AIRBEEPS_SECRET_KEY=$(openssl rand -hex 32)" | Out-File .env -Append

3. Install dependencies and initialize the database

uv sync --locked
uv run scripts/bootstrap.py init

4. Start the backend

uv run fastapi dev --port 8500 airbeeps/main.py

Backend runs at http://localhost:8500

5. Start the frontend (in another terminal)

cd frontend
cp .env.example .env
pnpm install
pnpm dev

Frontend runs at http://localhost:3000

6. Create your account

Open http://localhost:3000 and sign up. The first user becomes admin.

CLI reference

The airbeeps CLI is available after installing via pip:

Command	Description
airbeeps run	Start the server (runs migrations and seeding automatically)
airbeeps migrate	Run database migrations only
airbeeps migrate --show	Show current migration revision
airbeeps create-user	Create a new user (interactive prompts)
airbeeps create-user --email user@example.com --superuser	Create an admin user
airbeeps version	Show version information
airbeeps info	Show configuration information

airbeeps run options

Flag	Description	Default
--host / -h	Host to bind to	127.0.0.1
--port / -p	Port to bind to	8500
--reload	Enable auto-reload (dev mode)	false
--no-migrations	Skip database migrations	migrations enabled
--log-level	Logging level	info

Bootstrap script (development)

For development mode, bootstrap.py provides additional setup commands:

Command	Description
bootstrap.py init	Full initialization (migrations + seeding)
bootstrap.py migrate	Run migrations only
bootstrap.py config-init	Reseed system configs from YAML
bootstrap.py reset-db --force	Drop all data (dev only)
bootstrap.py superuser --email user@example.com	Create an admin manually
bootstrap.py list-superusers	List all admin users

All commands run from the backend/ directory with uv run scripts/.

Next steps

TIP

Configure your LLM provider first! Without one, the chat won't work.

1. Configure LLM providers at /admin/model-providers
2. Create your first assistant at /admin/assistants
3. Upload documents to a knowledge base at /admin/kbs
4. Start chatting!

See Configuration for all available settings.