Installation
Deploy Bifrost using Docker Compose
Prefer to watch first? This walkthrough covers installing Bifrost and a first look around.
Prerequisites
Section titled “Prerequisites”- Git
- Docker and Docker Compose installed
- 8 GB of memory on the host (recommended): the default stack runs two workers with a 2 GB limit each, plus the API, database and storage
Upgrading an Existing Installation
Section titled “Upgrading an Existing Installation”For an existing 1.4.1 deployment, follow Upgrade From 1.4.1 to 2.0. Update the images directly; people may need to sign in again. Supported SDK2 Apps do not require a rebuild. The guide covers API-fleet cutover and optional runtime cleanup.
Quick Start
Section titled “Quick Start”-
Clone the repository:
Terminal window git clone https://github.com/gobifrost/bifrost.gitcd bifrost -
Run the setup script:
Terminal window ./setup.shThis generates
.envwith secure random secrets for all services. -
Start all services:
Terminal window docker compose up -
Access the application at
http://localhost:3000The first user to register becomes the Platform Admin.

Windows 11 deployment
Section titled “Windows 11 deployment”To deploy Bifrost on Windows, use native PowerShell — no WSL or Bash required. Install Git for Windows and Docker Desktop (with the WSL2 backend enabled), then:
-
Clone and enter the repository:
Terminal window git clone https://github.com/gobifrost/bifrost.gitcd bifrost -
Run the PowerShell setup script:
Terminal window .\Initialize-Bifrost.ps1It prompts for your domain, generates
.envwith secure secrets, runsdocker compose up -d, and prints the access URL. Pass-Domainto skip the prompt;-NoStartto generate.envwithout launching. -
Access the application at the printed URL (
http://localhost:3000for a localhost deployment).
Initialize-Bifrost.ps1 is the PowerShell counterpart to setup.sh; it
generates the same .env and needs no openssl, sed, or Git Bash.
If winget fails on a fresh Windows image with 0x8a15000f, set the Windows
region, reset winget sources, then retry:
Set-WinHomeLocation -GeoId 244winget source reset --forcewinget source updateArchitecture Overview
Section titled “Architecture Overview”Docker Compose starts these services:
| Service | Purpose |
|---|---|
| api | FastAPI application - handles HTTP requests and runs schedules |
| client | React frontend served via nginx |
| worker | Runs every kind of work: workflows, agent runs, and platform jobs (2 replicas, 2 GB each) |
| postgres | Primary database, and the queue workers claim work from |
| pgbouncer | Connection pooler for PostgreSQL |
| redis | Sessions, cache, and sync execution results |
| seaweedfs | S3-compatible object storage for workspace files |
Environment Variables
Section titled “Environment Variables”The setup.sh script generates all required secrets automatically. You only need to edit .env for optional features.
Optional Configuration
Section titled “Optional Configuration”| Variable | Description |
|---|---|
BIFROST_DEFAULT_USER_EMAIL |
Skip setup wizard by pre-creating admin |
BIFROST_DEFAULT_USER_PASSWORD |
Password for default admin user |
BIFROST_CORS_ORIGINS |
Allowed origins for CORS (default: http://localhost:3000) |
Single Sign-On (Optional)
Section titled “Single Sign-On (Optional)”SSO providers (Microsoft, Google, OIDC) are configured in the UI, not via environment variables.
See Configure SSO for setup instructions.
Verify Installation
Section titled “Verify Installation”Check service health:
# View all container statusdocker compose ps
# Check API healthcurl http://localhost:3000/api/health
# View logsdocker compose logs -f apidocker compose logs -f workerProduction Considerations
Section titled “Production Considerations”Security
Section titled “Security”- Generate cryptographically secure values for
BIFROST_SECRET_KEYandPOSTGRES_PASSWORD - Use a reverse proxy (nginx, Traefik, Caddy) with TLS termination
- Consider using external secret management to populate
.env
Scaling Workers
Section titled “Scaling Workers”Workers take work by memory, not by a fixed number of slots. Each worker
accepts runs that fit within 85% of its memory limit, using the memory each
workflow has learned it needs (or the Memory Request set in the
workflow’s settings). The default docker-compose.yml runs two workers
limited to 2 GB each, which suits most high-memory jobs and leaves room for
agent runs; larger app builds may need more.
Increase worker replicas for higher throughput:
WORKER_REPLICAS=3 docker compose upOr scale dynamically:
docker compose up -d --scale worker=3For workflows that need more memory than a worker has, raise the worker’s
memory limit in docker-compose.yml instead. Work that no worker can hold
fails at once rather than waiting.
Kubernetes
Section titled “Kubernetes”For Kubernetes deployments:
- See the
k8s/directory for example manifests. Apply them withkubectl apply -k k8s/, which also grants the API the Role it needs to start worker Jobs. - The API starts worker Jobs as work arrives and stops them when idle. By default it keeps one warm and runs up to six, each with a 512Mi memory request and a 2Gi limit.
- Run two API replicas and two client replicas. The API also runs schedules and starts the workers, and a second replica takes over within about 25 seconds when one is lost.
- Consider managed PostgreSQL, Redis, and S3-compatible storage
Set scaling and isolation in Settings → Kubernetes → Scaling & Isolation. Changes apply without a restart:
- Scaling: Warm Workers, Max Workers, Worker Memory, Largest Worker (the most memory a worker sized for a large run can get), and Idle Time.
- Isolated Jobs: turn on Isolate Build Jobs to run build jobs, such as App and Solution deploys, each in its own pod, up to Max Isolated Pods at once, and choose which job types are isolated. With isolation off, these jobs run on workers.
Worker Jobs and isolated pods copy the API pod’s namespace, image and
configuration, so they usually need no settings of their own. To override
that, set the BIFROST_KUBERNETES_JOB_* variables (for example
BIFROST_KUBERNETES_JOB_IMAGE or BIFROST_KUBERNETES_JOB_SERVICE_ACCOUNT);
the older BIFROST_KUBERNETES_BUILD_* names still work, with a startup
warning to rename them.
See the Kubernetes worker sizing guide for measured memory use and draining behavior.
Upgrading From an Earlier Release
Section titled “Upgrading From an Earlier Release”Earlier releases ran a separate scheduler service alongside the workers and
used RabbitMQ (and, on Kubernetes, optionally KEDA) to queue work. Bifrost now
runs one kind of worker for every job type, schedules from the API, and queues
work in PostgreSQL.
Docker Compose
Section titled “Docker Compose”An unchanged compose file keeps working: its scheduler service runs the same
worker, so it acts as a second worker. To switch to the current layout, take
the current docker-compose.yml (one worker service with two replicas and a
2 GB limit each), then retire the old scheduler container:
docker compose up -d --remove-orphansKeep the rabbitmq service and the BIFROST_RABBITMQ_URL settings for the
first start after upgrading: the API moves any runs an earlier release left
queued there into PostgreSQL. Once the API logs
Drained work queued by an earlier release, delete the rabbitmq service,
its depends_on entries, the BIFROST_RABBITMQ_URL lines and the
rabbitmq_data volume from the compose file, remove RABBITMQ_PASSWORD from
.env, then run:
docker compose up -d --remove-orphansdocker volume rm bifrost_rabbitmq_dataBIFROST_MAX_CONCURRENCY, BIFROST_MAX_WORKERS and
BIFROST_MAX_SERVICE_WORKERS are no longer used; remove them if you set them.
The API logs a warning at startup naming every variable it no longer reads.
Kubernetes
Section titled “Kubernetes”Apply the new base manifests with kubectl apply -k k8s/. They set the old
bifrost-worker and bifrost-scheduler Deployments to zero replicas, and the
API’s worker Jobs take over. Once their pods are gone, delete them:
kubectl -n bifrost delete deployment bifrost-worker bifrost-schedulerOn first start, the API copies the scaling and isolation variables you set
(such as BIFROST_POOL_MIN_WORKERS, BIFROST_POOL_MAX_WORKERS,
BIFROST_KUBERNETES_BUILD_MAX_JOBS and BIFROST_PLATFORM_BUILD_BACKEND) into
Settings → Kubernetes → Scaling & Isolation once, and each imported value
shows the variable it came from. After that, those variables are no longer
read; the page lists any that are still set so you can remove them.
Keep RabbitMQ running until the API logs
Drained work queued by an earlier release, then remove the rabbitmq
Deployment and Service and any KEDA ScaledObject and
TriggerAuthentication that targeted bifrost-worker. See Removing RabbitMQ
and KEDA after
upgrading
for the exact commands.