Local setup

Prerequisites

• Docker Desktop
• At least one provider API key: OpenAI, Azure OpenAI, or Anthropic

1. Configure environment

cp .env.example .env

Fill AUTH_SECRET, ZEALLM_ENCRYPTION_KEY (64 hex characters), admin emails and POSTGRES_PASSWORD. Generate secrets in PowerShell:

[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Max 256 }))   # AUTH_SECRET
-join ((1..64) | ForEach-Object { '{0:x}' -f (Get-Random -Max 16) })          # ZEALLM_ENCRYPTION_KEY

Critical: never rotate ZEALLM_ENCRYPTION_KEY after provider credentials are stored unless you follow the rotation runbook.

The full variable list is in Environment variables.

2. Start the stack

docker compose up -d --build

Service	URL
Portal	http://localhost:3000
Gateway	http://localhost:8080 (GET /health)
Docs	http://localhost:3002
Postgres	host port 55432 (local override only)

Postgres is published on 55432 via docker-compose.override.yml, which Compose loads automatically for local docker compose up. Production must deploy with docker compose -f docker-compose.yml so that override is skipped.

Sign in

1. Open http://localhost:3000 and select Sign in (or Get started), or go straight to http://localhost:3000/login
2. With AUTH_DEV_BYPASS=true, enter a bootstrap admin email (listed in ZEALLM_ADMIN_EMAILS) in Email address and select Sign in — no password is required. The field is prefilled with the first address in ZEALLM_ADMIN_EMAILS.
3. The first admin sign-in bootstraps an OpenAI credential if OPENAI_API_KEY is set

When Microsoft Entra ID is configured (AZURE_AD_*), the page also shows Continue with Microsoft. With neither option enabled, it shows that sign-in is unavailable.

After sign-in you land on the Dashboard. Navigating the portal explains the sidebar and top bar.

The platform is invite-only. Sign-in is rejected unless the email is a bootstrap admin or was invited under Users. All emails must match ZEALLM_ALLOWED_DOMAIN.