Configuration
Hive-Pal is configured entirely through environment variables on the app container. This page is the complete reference.
Required
| Variable | Description |
|---|---|
DATABASE_URL | PostgreSQL connection string, e.g. postgres://postgres:postgres@postgres:5432/beekeeper |
BETTER_AUTH_SECRET | Secret used to sign Better Auth sessions/cookies. Use 32+ random chars: openssl rand -base64 32 |
BETTER_AUTH_URL | Public base URL where the app and /api/auth/* are served, e.g. https://hive.example.com |
FRONTEND_URL | Public URL of the app. Used in email links and as a trusted auth origin |
ADMIN_EMAIL | Initial admin account email (seeded on startup) |
ADMIN_PASSWORD | Initial admin password (plaintext; hashed on first run) |
Because the app serves the frontend and API from the same origin, you do not need to set VITE_API_URL or API_URL for the standard single-container deployment. Those are only relevant for split frontend/backend or local development setups.
Authentication
Hive-Pal authenticates with Better Auth. Beyond the required BETTER_AUTH_SECRET and BETTER_AUTH_URL:
| Variable | Description | Default |
|---|---|---|
PASSKEY_RP_ID | WebAuthn relying-party ID for passkeys. Set to your domain in production | localhost |
COOKIE_DOMAIN | Set when frontend and backend share a parent domain across subdomains (e.g. .example.com) | — |
ALLOWED_ORIGINS | Comma-separated list of allowed CORS origins | — |
JWT_SECRET | Signs short-lived tokens for iCal calendar feeds, HiveScale proxy requests, and local-storage download URLs (see note below). Generate with openssl rand -base64 32 | — |
JWT_SECRET is not used for user authentication (that's Better Auth). It only signs short-lived tokens for iCal calendar feeds, HiveScale proxy requests, and local-storage download URLs. Set it only if you use those features.
Single sign-on (OIDC / Authentik)
Hive-Pal can sign users in through any OpenID Connect provider. It has been designed with Authentik in mind. SSO is enabled as soon as the issuer (or discovery URL), client ID and client secret are set.
| Variable | Description | Default |
|---|---|---|
OIDC_ISSUER | Issuer URL of the provider. Authentik: https://auth.example.com/application/o/<app-slug>/ | — |
OIDC_DISCOVERY_URL | Full discovery URL; overrides the one derived from OIDC_ISSUER | <OIDC_ISSUER>/.well-known/openid-configuration |
OIDC_CLIENT_ID | Client ID of the OAuth2/OpenID provider | — |
OIDC_CLIENT_SECRET | Client secret of the OAuth2/OpenID provider | — |
OIDC_PROVIDER_ID | Internal provider ID, used in the redirect URI | authentik |
OIDC_SCOPES | Requested scopes (space- or comma-separated) | openid profile email |
OIDC_BUTTON_LABEL | Text of the login button | Sign in with SSO |
OIDC_ALLOW_SIGNUP | Create a Hive-Pal account on the first SSO login when no account with that email exists. With false, only existing users can sign in via SSO | true |
DISABLE_LOCAL_LOGIN | Disable password, magic-link and passkey sign-in as well as email sign-up, so that only SSO remains. Ignored while SSO is not configured | false |
How users are matched: accounts are matched by email address (case-insensitive). The provider's email claim is trusted even when it doesn't send email_verified=true, so make sure users can't change their own email address in Authentik.
When SSO is linked implicitly to an existing account whose email was never verified (typically an account registered with a password), the password, passkeys and sessions of that account are removed. This prevents someone from pre-registering an account with another person's email and keeping access after that person's first SSO login. The owner keeps all data and can still set a password again via "Forgot password". Accounts with a verified email (older accounts, magic-link users), and accounts linked by their owner from Settings → Linked accounts, keep their password. Google and Facebook sign-in (see below) follow the same rules.
Users created through SSO, Google or Facebook are asked once to accept the privacy policy after their first login.
Authentik setup
-
In Authentik, go to Applications → Providers and create an OAuth2/OpenID Provider:
- Client type: Confidential
- Redirect URIs (strict):
<BETTER_AUTH_URL>/api/auth/callback/authentik, e.g.https://hive.example.com/api/auth/callback/authentik. If you changedOIDC_PROVIDER_ID, use that value instead ofauthentik. - Scopes: keep the default
openid,emailandprofilemappings.
-
Create an Application that uses this provider and note its slug. Bind users or groups to it to control who may sign in.
-
Configure Hive-Pal:
OIDC_ISSUER=https://auth.example.com/application/o/<app-slug>/OIDC_CLIENT_ID=<client id>OIDC_CLIENT_SECRET=<client secret>OIDC_BUTTON_LABEL="Sign in with Authentik"# OIDC_ALLOW_SIGNUP=false # only allow existing Hive-Pal users# DISABLE_LOCAL_LOGIN=true # SSO only -
Restart Hive-Pal. The login page now shows the SSO button.
Keep local login enabled until you have confirmed that SSO works. Users with ADMIN_EMAIL get the admin role no matter how they sign in.
Google and Facebook sign-in
Each provider is enabled as soon as its client ID and secret are set. The login and registration pages then show a Continue with Google / Continue with Facebook button, and users can link or unlink these accounts under Settings → Linked accounts. Both can be used alongside password login and OIDC SSO.
| Variable | Description | Default |
|---|---|---|
GOOGLE_CLIENT_ID | OAuth client ID from the Google Cloud console | — |
GOOGLE_CLIENT_SECRET | OAuth client secret | — |
FACEBOOK_CLIENT_ID | Facebook app ID | — |
FACEBOOK_CLIENT_SECRET | Facebook app secret | — |
Redirect URIs to register with the provider:
- Google:
<BETTER_AUTH_URL>/api/auth/callback/google - Facebook:
<BETTER_AUTH_URL>/api/auth/callback/facebook
Accounts are matched by email address, as with OIDC. Google sign-in only links to an existing account when Google reports the address as verified. Facebook sends only confirmed addresses but never says so, so Hive-Pal trusts the email Facebook returns. Users whose Facebook account has no email address can't sign in with it.
Google setup
- In the Google Cloud console, configure the OAuth consent screen (scopes
openid,email,profile). - Create an OAuth client ID of type Web application and add the redirect URI above under Authorized redirect URIs.
- Set
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETand restart Hive-Pal.
Facebook setup
- In Meta for Developers, create an app with the Authenticate and request data from users with Facebook Login use case, and add the
emailpermission. - Under Facebook Login → Settings, add the redirect URI above to Valid OAuth Redirect URIs.
- Copy the App ID and App secret from App settings → Basic into
FACEBOOK_CLIENT_IDandFACEBOOK_CLIENT_SECRETand restart Hive-Pal. The app must be switched to Live mode before people outside your developer team can sign in. - Before going Live, Facebook asks for a Privacy Policy URL and a User data deletion URL under App settings → Basic. Use
<FRONTEND_URL>/privacy-policyand choose Data deletion instructions URL with<FRONTEND_URL>/data-deletion. Both pages name the hivepal.app operator and contact address, so self-hosted instances should point Facebook at their own pages instead.
AI assistants (MCP)
Hive-Pal serves an MCP endpoint at <BETTER_AUTH_URL>/api/mcp and acts as the OAuth server MCP clients sign in through (see Connecting AI assistants).
| Variable | Description | Default |
|---|---|---|
MCP_ENABLED | Set to false to turn off the MCP endpoint and the OAuth provider | true |
MCP requires BETTER_AUTH_URL to be https:// (plain http:// works only on localhost), so it is switched off automatically on deployments served over plain http. If a reverse proxy sits in front of Hive-Pal, it must also forward /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server and /.well-known/openid-configuration to the backend.
Email
Email powers magic-link sign-in and password-reset messages. Hive-Pal supports Resend or SMTP and auto-selects based on what's configured. Without email, password and passkey login still work, but magic links and password resets do not.
| Variable | Description |
|---|---|
MAIL_PROVIDER | Force a provider: resend, smtp, or none. Auto-selects if unset |
FROM_EMAIL | Sender address for outgoing mail |
RESEND_API_KEY | API key for the Resend provider |
SMTP_HOST | SMTP server hostname |
SMTP_PORT | SMTP server port (e.g. 587 or 465) |
SMTP_USER | SMTP username |
SMTP_PASS | SMTP password (for Gmail, use an App Password) |
SMTP_SECURE | true for port 465 (SSL), false for 587 (TLS) |
SMTP_REJECT_UNAUTHORIZED | Reject invalid TLS certs. Default true; set false for self-signed certs |
File Storage
Hive-Pal stores uploaded audio recordings and photos in either the local filesystem or S3-compatible object storage. Choose with STORAGE_TYPE.
| Variable | Description | Default |
|---|---|---|
STORAGE_TYPE | local or s3 | s3 |
STORAGE_LOCAL_PATH | Directory for local storage. In Docker this is backed by the uploads volume | /data/uploads |
AUDIO_MAX_FILE_SIZE | Max request size for audio uploads, in bytes | 52428800 (50 MB) |
INSPECTION_AUDIO_MAX_FILE_SIZE | Max size of a single inspection recording, in bytes. A recording must fit under both limits, so with the defaults the effective limit is 10 MB | 10485760 (10 MB) |
BACKEND_PUBLIC_URL | Public URL of the app, used to build absolute download links for locally stored files. Needed when something outside the container downloads files, such as a pull-mode AI worker | — |
Local storage
The simplest option — no external services. Mount a volume at /data/uploads:
STORAGE_TYPE=local
STORAGE_LOCAL_PATH=/data/uploads
Download URLs are signed, time-limited paths (HMAC-SHA256 with JWT_SECRET), so they behave like S3 pre-signed URLs.
S3-compatible storage
Use AWS S3, MinIO, or any S3-compatible service:
STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com # or your MinIO endpoint
S3_REGION=us-east-1
S3_BUCKET=hivepal-uploads
S3_ACCESS_KEY_ID=your_key
S3_SECRET_ACCESS_KEY=your_secret
HiveScale Integration
Hive-Pal can proxy live data from a separate HiveScale backend.
| Variable | Description |
|---|---|
HIVESCALE_API_BASE_URL | Base URL of the HiveScale backend |
HIVESCALE_SERVICE_API_KEY | Shared service key used by Hive-Pal to call HiveScale |
JWT_SECRET | Signs the per-user tokens Hive-Pal forwards to HiveScale |
The HIVESCALE_SERVICE_API_KEY value must match HIVEPAL_SERVICE_API_KEY on the HiveScale backend, and JWT_SECRET must match HiveScale's HIVEPAL_JWT_SECRET so it can verify the forwarded user tokens. HiveScale remains the source of truth for measurements, device roles, off-grid telemetry, and calibration; Hive-Pal only proxies authenticated user requests. See the HiveScale guide.
AI (Voice Inspections & Assistant)
Voice inspections (transcribing recordings and drafting inspection fields from them) and the Apiary Assistant need a separate AI service: the ghcr.io/martinhrvn/hivepal-ai image, built from apps/ai-app. The setup steps are in Docker Setup → Enabling Voice Inspections. This section lists the variables on the app container.
| Variable | Description | Default |
|---|---|---|
AI_ENABLED | Set to true to turn on AI analysis and the Assistant. Otherwise both return "AI is disabled" | — |
AI_PROCESSING_MODE | How audio jobs reach the AI service: push (the app calls the AI service over HTTP), pull (a worker polls the app for jobs) or auto (pull, but the app pushes any job no worker has claimed after AI_PULL_FALLBACK_MINUTES) | push |
AI_SERVICE_BASE_URL | URL of the AI service, used by push mode and the Assistant | http://hivepal-ai:8008 |
AI_API_KEY | Shared secret sent as a Bearer token to the AI service. Must match AI_API_KEY on the AI service. In push mode, jobs stay pending until it is set | — |
AI_REQUEST_TIMEOUT_MS | Timeout for calls to the AI service, in milliseconds | 300000 (5 min) |
AI_PULL_FALLBACK_MINUTES | In auto mode, how long a job waits for a worker before the app pushes it | 10 |
WORKER_JOB_LEASE_MS | How long a pull worker holds a claimed job before it is requeued. Raise it if long recordings take longer than this to transcribe | 300000 (5 min) |
OLLAMA_MODEL | Model the Assistant asks the AI service to use. If unset, the AI service uses its own default | — |
A pull worker downloads recordings from the app. With STORAGE_TYPE=local, set BACKEND_PUBLIC_URL to a URL the worker can reach, and set JWT_SECRET, which signs the download links. Otherwise the worker receives a relative link it cannot download. With S3 the worker gets a pre-signed S3 URL instead.
Error Tracking (Optional)
Configure Sentry to monitor errors in production.
| Variable | Description |
|---|---|
SENTRY_DSN | Backend Sentry DSN |
SENTRY_ENVIRONMENT | Backend environment label (e.g. production) |
VITE_SENTRY_DSN | Frontend Sentry DSN |
VITE_SENTRY_ENVIRONMENT | Frontend environment label |
Other
| Variable | Description | Default |
|---|---|---|
NODE_ENV | Runtime mode | production |
Best Practices
- Never commit secrets to version control — use an
.envfile or your orchestrator's secret store. - Generate
BETTER_AUTH_SECRETwithopenssl rand -base64 32and keep it stable; changing it invalidates existing sessions. - Set
BETTER_AUTH_URL,FRONTEND_URL, andPASSKEY_RP_IDto your real public domain before going live.BETTER_AUTH_URLalso determines the SSO redirect URI. - Configure email so users can reset passwords and use magic links.