Distribution

Airbeeps is distributed as a Python wheel that bundles the backend and pre-built frontend.

Quick install

pip install airbeeps
airbeeps run

Building from source

Prerequisites

• Python 3.13+
• Node.js 20+
• uv and pnpm

Build the wheel

git clone https://github.com/airbeeps/airbeeps.git
cd airbeeps
python scripts/build_wheel.py

This script:

1. Installs frontend dependencies (pnpm install)
2. Builds the Nuxt frontend (pnpm generate)
3. Copies the build output into the backend package
4. Builds the Python wheel with hatchling

The resulting .whl file is placed in backend/dist/.

Package structure

airbeeps-<version>.whl
├── airbeeps/
│   ├── main.py              # FastAPI app
│   ├── config.py             # Settings
│   ├── cli.py                # CLI commands
│   ├── rag/                  # RAG pipeline
│   ├── agents/               # Agent system
│   ├── frontend_dist/        # Bundled Nuxt build
│   └── ...
└── airbeeps-<version>.dist-info/

Installation modes

Installed mode (from PyPI or wheel)

pip install airbeeps
airbeeps run

• Data stored in platform directory (via platformdirs)
  • Linux: ~/.local/share/airbeeps/
  • macOS: ~/Library/Application Support/airbeeps/
  • Windows: ~\AppData\Local\airbeeps\
• Frontend served from bundled frontend_dist/
• Database at {data_dir}/airbeeps.db by default

Development mode (from source)

cd backend
uv sync --locked
uv run scripts/bootstrap.py init
uv run fastapi dev --port 8500 airbeeps/main.py

• Data stored in backend/data/
• Frontend runs separately via pnpm dev on port 3000

CLI commands

Command	Description
airbeeps run	Start the server
airbeeps migrate	Run database migrations
airbeeps migrate --show	Show current migration revision
airbeeps create-user	Create a user (interactive)
airbeeps create-user --email user@example.com --superuser	Create an admin
airbeeps version	Show version info
airbeeps info	Show configuration details

airbeeps run flags

Flag	Default	Description
--host / -h	127.0.0.1	Host to bind
--port / -p	8500	Port to bind
--reload	false	Auto-reload on changes (dev)
--no-migrations	false	Skip auto-migrations
--log-level	info	Log level

Version management

Airbeeps uses hatch-vcs for dynamic versioning based on Git tags.

Releases

git tag v0.2.0
git push origin v0.2.0

The version is derived from the latest Git tag automatically.

Development builds

Without a tag, the version includes a development suffix:

0.1.5.dev3+g8c3ede9

Publishing to PyPI

python scripts/build_wheel.py
twine upload backend/dist/*

The GitHub Actions release workflow automates this: tag a release and the CI builds and publishes to PyPI.

Optional dependencies

Install extras for production features:

# Redis caching
pip install airbeeps[redis]

# Celery task queue
pip install airbeeps[celery]

# All production extras
pip install airbeeps[production]

Testing the build

# Install in a clean venv
python -m venv /tmp/test-airbeeps
source /tmp/test-airbeeps/bin/activate  # or .\Scripts\Activate.ps1 on Windows
pip install backend/dist/airbeeps-*.whl

# Verify
airbeeps version
airbeeps info
airbeeps run --port 9000

Troubleshooting

Issue	Solution
ModuleNotFoundError: airbeeps	Ensure pip install completed without errors
Version shows 0.0.0	Ensure Git tags are pushed: git push origin --tags
Frontend not loading	Check that frontend_dist/ exists inside the wheel
Database migration errors	Run airbeeps migrate manually
Port already in use	Use --port to change: airbeeps run --port 9000