Installation

Server

HiveGuard is distributed as a Docker image. The recommended way to run it is Docker Compose.

Docker Compose (recommended)

git clone https://github.com/your-org/hiveguard
cd hiveguard
docker compose up --build -d

The docker-compose.yml starts:

• api — FastAPI server on port 8000
• db — PostgreSQL
• redis — session cache and config store

From source (development)

git clone https://github.com/your-org/hiveguard
cd hiveguard
uv sync --frozen --extra dev
uv run uvicorn hiveguard.main:app --reload

Requires PostgreSQL and Redis running locally. Set environment variables:

export DATABASE_URL=postgresql+asyncpg://user:pass@localhost/hiveguard
export REDIS_URL=redis://localhost:6379
export TARGET_URL=http://localhost:8080
export SECRET_KEY=dev-secret
export DASHBOARD_USERNAME=admin
export DASHBOARD_PASSWORD=admin

CLI

pip / uv (recommended)

pip install hiveguard-cli
# or
uv pip install hiveguard-cli

pipx (isolated, no venv management)

pipx install hiveguard-cli

From the monorepo

uv pip install -e apps/cli

Verify

hiveguard --version
hiveguard health

Dashboard

The dashboard SPA is embedded in the server. Open http://localhost:8000/dashboard in your browser and log in with your DASHBOARD_USERNAME / DASHBOARD_PASSWORD.

No separate installation needed.

Environment variables

Variable	Required	Default	Description
TARGET_URL	yes	—	The upstream service HiveGuard proxies to
DATABASE_URL	yes	—	PostgreSQL async URL (postgresql+asyncpg://...)
SECRET_KEY	yes	—	Random string for session signing
DASHBOARD_USERNAME	yes	—	HTTP Basic username for dashboard access
DASHBOARD_PASSWORD	yes	—	HTTP Basic password for dashboard access
REDIS_URL	no	redis://redis:6379	Redis connection URL
LOG_LEVEL	no	INFO	Python logging level