Happier Docs
Deployment

Environment variables

Configuration for the Happier Server.

This page is the runtime environment-variable reference for apps/server.

Notes:

  • Legacy aliases prefixed with HAPPY_ are still accepted where listed, but HAPPIER_ is preferred.
  • Billing/subscription provider secrets are intentionally not documented on this page.

Canonical template

Use /apps/server/.env.example as the canonical template.

Typical workflow:

cp apps/server/.env.example apps/server/.env

Then:

  • local/dev: load values from apps/server/.env,
  • Docker/Compose/platforms: copy the same key/value set into your deployment env/secret manager.

Core runtime

  • PORT (default 3005)
  • HAPPIER_SERVER_HOST (alias: HAPPY_SERVER_HOST, default 0.0.0.0)
  • NODE_ENV
  • SERVER_ROLE (all | api | worker, default all)
  • HANDY_MASTER_SECRET (required unless auto-generated in light flavor)
  • DATABASE_URL (required for full flavor; optional for light)
  • HAPPIER_DB_PROVIDER (alias: HAPPY_DB_PROVIDER)
    Values: postgres | mysql | pglite | sqlite
  • HAPPIER_FILES_BACKEND (alias: HAPPY_FILES_BACKEND)
    Values: s3 | local
  • HAPPIER_SOCKET_ADAPTER (alias: HAPPY_SOCKET_ADAPTER)
    Values: memory | redis-streams
  • HAPPIER_SOCKET_REDIS_ADAPTER (alias: HAPPY_SOCKET_REDIS_ADAPTER)
    Legacy boolean toggle; prefer HAPPIER_SOCKET_ADAPTER=redis-streams
  • REDIS_URL (required when Redis adapter is enabled)
  • HAPPIER_INSTANCE_ID (alias: HAPPY_INSTANCE_ID)
    Stable process identifier for logs/cluster behavior
  • METRICS_ENABLED (default true)
  • METRICS_PORT (default 9090)

Networking / reverse proxy

  • HAPPIER_SERVER_TRUST_PROXY (optional)
    Controls whether the server trusts X-Forwarded-* headers for client IP / protocol when running behind a reverse proxy.
    • unset: use framework defaults (do not trust forwarded headers)
    • true / 1: trust all proxy hops (only safe if the server is not directly reachable)
    • false / 0: never trust forwarded headers
    • <number>: trust the last N hops (recommended for typical single-proxy setups: 1)

API rate limits

Rate limiting is implemented via @fastify/rate-limit. Each *_WINDOW value accepts human-readable durations like 30 seconds, 1 minute, 5 minutes.

Global controls:

  • HAPPIER_API_RATE_LIMITS_ENABLED (default true)
    Set to 0/false to disable all API rate limits.
  • HAPPIER_API_RATE_LIMITS_GLOBAL_MAX (default 0)
    Optional global limit applied to all routes. Set to 0 to disable.
  • HAPPIER_API_RATE_LIMITS_GLOBAL_WINDOW (default 1 minute)
  • HAPPIER_API_RATE_LIMIT_KEY_MODE (default auth-or-ip)
    Controls how rate limits are keyed:
    • auth-or-ip: prefer a hashed Authorization header, fall back to client IP
    • auth-only: always key by Authorization (unauthenticated requests share a single bucket)
    • ip-only: always key by client IP
  • HAPPIER_API_RATE_LIMIT_CLIENT_IP_SOURCE (default fastify)
    Controls how the client IP is derived when IP-keying is used:
    • fastify: use the framework-derived request.ip (recommended; configure HAPPIER_SERVER_TRUST_PROXY behind a reverse proxy)
    • x-forwarded-for: derive from X-Forwarded-For (only safe when the server is not directly reachable)
    • x-real-ip: derive from X-Real-Ip (only safe when the server is not directly reachable)

Hot endpoints (set *_MAX=0 to disable a specific limit):

  • HAPPIER_SESSION_MESSAGES_RATE_LIMIT_MAX (default 600)
  • HAPPIER_SESSION_MESSAGES_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_SESSION_MESSAGES_BY_LOCAL_ID_RATE_LIMIT_MAX (default 600)
  • HAPPIER_SESSION_MESSAGES_BY_LOCAL_ID_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_SESSIONS_LIST_RATE_LIMIT_MAX (default 300)
  • HAPPIER_SESSIONS_LIST_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_CHANGES_RATE_LIMIT_MAX (default 600)
  • HAPPIER_CHANGES_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_FEATURES_RATE_LIMIT_MAX (default 120)
  • HAPPIER_FEATURES_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_MACHINES_RATE_LIMIT_MAX (default 300)
  • HAPPIER_MACHINES_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_ARTIFACTS_RATE_LIMIT_MAX (default 300)
  • HAPPIER_ARTIFACTS_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_FEED_RATE_LIMIT_MAX (default 300)
  • HAPPIER_FEED_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_KV_LIST_RATE_LIMIT_MAX (default 600)
  • HAPPIER_KV_LIST_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_ACCOUNT_PROFILE_RATE_LIMIT_MAX (default 300)
  • HAPPIER_ACCOUNT_PROFILE_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_ACCOUNT_SETTINGS_RATE_LIMIT_MAX (default 300)
  • HAPPIER_ACCOUNT_SETTINGS_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_SESSION_PENDING_RATE_LIMIT_MAX (default 600)
  • HAPPIER_SESSION_PENDING_RATE_LIMIT_WINDOW (default 1 minute)
  • HAPPIER_SESSION_PENDING_MATERIALIZE_RATE_LIMIT_MAX (default 120)
  • HAPPIER_SESSION_PENDING_MATERIALIZE_RATE_LIMIT_WINDOW (default 1 minute)

Storage backends

  • S3_HOST
  • S3_PORT (optional)
  • S3_USE_SSL (true/false, default true)
  • S3_BUCKET
  • S3_PUBLIC_URL
  • S3_ACCESS_KEY
  • S3_SECRET_KEY

Light flavor paths

  • HAPPIER_SERVER_LIGHT_DATA_DIR (alias: HAPPY_SERVER_LIGHT_DATA_DIR)
  • HAPPIER_SERVER_LIGHT_DB_DIR (alias: HAPPY_SERVER_LIGHT_DB_DIR)
  • HAPPIER_SERVER_LIGHT_FILES_DIR (alias: HAPPY_SERVER_LIGHT_FILES_DIR)
  • PUBLIC_URL (optional; used for light defaults)

Bug reports

  • HAPPIER_FEATURE_BUG_REPORTS__ENABLED (default 1)
  • HAPPIER_FEATURE_BUG_REPORTS__PROVIDER_URL (default https://reports.happier.dev)
  • HAPPIER_FEATURE_BUG_REPORTS__DEFAULT_INCLUDE_DIAGNOSTICS (default 1)
  • HAPPIER_FEATURE_BUG_REPORTS__MAX_ARTIFACT_BYTES (default 10485760)
  • HAPPIER_FEATURE_BUG_REPORTS__UPLOAD_TIMEOUT_MS (default 120000)
  • HAPPIER_FEATURE_BUG_REPORTS__CONTEXT_WINDOW_MS (default 1800000; min 1000, max 86400000)
  • HAPPIER_FEATURE_BUG_REPORTS__ACCEPTED_ARTIFACT_KINDS (CSV allowlist)

Server diagnostics snapshot controls

  • HAPPIER_BUG_REPORTS_SERVER_DIAGNOSTICS_ENABLED (default 0)
  • HAPPIER_BUG_REPORTS_SERVER_DIAGNOSTICS_ACCESS_MODE (default owner, allowed: authenticated, owner)
  • HAPPIER_SERVER_OWNER_USER_IDS (CSV user ids; used when access mode is owner)
  • HAPPIER_BUG_REPORTS_SERVER_LOG_PATH
  • HAPPIER_SELF_HOST_LOG_DIR (fallback directory for server.log)
  • HAPPIER_BUG_REPORTS_SERVER_LOG_MAX_BYTES (default 262144)
  • HAPPIER_BUG_REPORTS_SERVER_DIAGNOSTICS_RATE_LIMIT_MAX (default 30)
  • HAPPIER_BUG_REPORTS_SERVER_DIAGNOSTICS_RATE_LIMIT_WINDOW (default 1 minute)

Owner-id note:

  • HAPPIER_SERVER_OWNER_USER_IDS expects Happier account ids.
  • Owners can find their account id in the app under Settings → Account.

OAuth and auth

For policy behavior and examples, see Server Auth.

Global auth policy

  • AUTH_ANONYMOUS_SIGNUP_ENABLED
  • AUTH_SIGNUP_PROVIDERS (CSV)
  • AUTH_REQUIRED_LOGIN_PROVIDERS (CSV)
  • AUTH_OFFBOARDING_ENABLED
  • AUTH_OFFBOARDING_INTERVAL_SECONDS
  • AUTH_OFFBOARDING_STRICT
  • AUTH_RECOVERY_PROVIDER_RESET_ENABLED
  • AUTH_UI_AUTO_REDIRECT
  • AUTH_UI_AUTO_REDIRECT_PROVIDER_ID
  • AUTH_UI_RECOVERY_KEY_REMINDER_ENABLED
  • AUTH_PROVIDERS_CONFIG_PATH
  • AUTH_PROVIDERS_CONFIG_JSON
  • AUTH_ACCOUNT_DISABLED_TTL_SECONDS

Built-in key-challenge login route

Happier’s default “device-key” signup/login flow uses POST /v1/auth.

Server operators can disable this built-in login route (for example when all access should go through a provider like GitHub/OIDC).

  • HAPPIER_FEATURE_AUTH_LOGIN__KEY_CHALLENGE_ENABLED (default 1)

Note: if you disable the key-challenge route, ensure you have at least one viable provider configured (otherwise the server will fail fast at boot to prevent lockouts).

GitHub OAuth

  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET
  • GITHUB_REDIRECT_URL (legacy alias: GITHUB_REDIRECT_URI)
  • GITHUB_HTTP_TIMEOUT_SECONDS
  • GITHUB_STORE_ACCESS_TOKEN
  • GITHUB_WEBHOOK_SECRET
  • GITHUB_APP_ID
  • GITHUB_PRIVATE_KEY
  • GITHUB_OAUTH_PENDING_TTL_SECONDS (legacy fallback for pending TTL)
  • HAPPIER_WEBAPP_URL (alias: HAPPY_WEBAPP_URL)
  • HAPPIER_WEBAPP_OAUTH_RETURN_URL_BASE (alias: HAPPY_WEBAPP_OAUTH_RETURN_URL_BASE)
  • HAPPIER_OAUTH_RETURN_ALLOWED_SCHEMES (alias: HAPPY_OAUTH_RETURN_ALLOWED_SCHEMES)
  • OAUTH_PENDING_TTL_SECONDS
  • OAUTH_STATE_TTL_SECONDS

Note on “optional” web app URL env vars:

  • HAPPIER_WEBAPP_URL / HAPPIER_WEBAPP_OAUTH_RETURN_URL_BASE are only “optional” if you are using the hosted client at https://app.happier.dev.
    • If you are self-hosting the web app, or using a local dev web UI, you must set one of these so the server can redirect back to your client after OAuth.

GitHub eligibility restrictions

  • AUTH_GITHUB_ALLOWED_USERS
  • AUTH_GITHUB_ALLOWED_ORGS
  • AUTH_GITHUB_ORG_MATCH
  • AUTH_GITHUB_ORG_MEMBERSHIP_SOURCE
  • AUTH_GITHUB_APP_ID
  • AUTH_GITHUB_APP_PRIVATE_KEY
  • AUTH_GITHUB_APP_INSTALLATION_ID_BY_ORG

Account / terminal auth TTL controls

  • ACCOUNT_AUTH_REQUEST_TTL_SECONDS
  • TERMINAL_AUTH_REQUEST_TTL_SECONDS
  • TERMINAL_AUTH_CLAIM_RETRY_WINDOW_SECONDS
  • VENDOR_TOKEN_MAX_LEN

Encryption / plaintext storage (E2EE opt-out)

For an overview and operator guidance, see Server → Encryption & plaintext storage.

Server-wide storage policy:

  • HAPPIER_FEATURE_ENCRYPTION__STORAGE_POLICY (default required_e2ee) Values: required_e2ee | optional | plaintext_only

Account-level opt-out (only meaningful when policy is optional):

  • HAPPIER_FEATURE_ENCRYPTION__ALLOW_ACCOUNT_OPTOUT (default 0)
  • HAPPIER_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODE (default e2ee) Values: e2ee | plain

Friends / social

  • HAPPIER_FEATURE_SOCIAL_FRIENDS__ENABLED
  • HAPPIER_FEATURE_SOCIAL_FRIENDS__ALLOW_USERNAME
  • HAPPIER_FEATURE_SOCIAL_FRIENDS__IDENTITY_PROVIDER
  • FRIENDS_USERNAME_MIN_LEN
  • FRIENDS_USERNAME_MAX_LEN
  • FRIENDS_USERNAME_REGEX

Voice

Happier voice/server tokening controls:

  • HAPPIER_FEATURE_VOICE__ENABLED
  • HAPPIER_FEATURE_VOICE__REQUIRE_SUBSCRIPTION
  • VOICE_FREE_SESSIONS_PER_MONTH
  • VOICE_FREE_MINUTES_PER_MONTH
  • VOICE_MAX_CONCURRENT_SESSIONS
  • VOICE_MAX_SESSION_SECONDS
  • VOICE_MAX_MINUTES_PER_DAY
  • VOICE_TOKEN_MAX_PER_MINUTE
  • VOICE_COMPLETE_MAX_PER_MINUTE
  • VOICE_LEASE_CLEANUP
  • VOICE_LEASE_RETENTION_DAYS
  • VOICE_LEASE_CLEANUP_INTERVAL_MS
  • ELEVENLABS_API_KEY
  • ELEVENLABS_AGENT_ID
  • ELEVENLABS_AGENT_ID_PROD

UI/static serving

  • HAPPIER_SERVER_UI_DIR (alias: HAPPIER_SERVER_LIGHT_UI_DIR)
  • HAPPIER_SERVER_UI_PREFIX (alias: HAPPIER_SERVER_LIGHT_UI_PREFIX)
  • HAPPIER_SERVER_UI_REQUIRED (alias: HAPPIER_SERVER_LIGHT_UI_REQUIRED)
  • HAPPIER_SERVER_UI_DEBUG_PATH (debug fallback path visibility)

Background / maintenance jobs

  • HAPPY_ACCOUNT_CHANGE_CLEANUP
  • HAPPY_ACCOUNT_CHANGE_CLEANUP_INTERVAL_MS
  • HAPPY_PRESENCE_STREAM_MAXLEN

Advanced / debug controls

  • HAPPY_EXIT_ON_FATAL
  • HAPPY_SOCKET_ROOMS_ONLY
  • HAPPIER_RPC_FORWARD_TIMEOUT_MS
  • HAPPIER_RPC_FORWARD_CAPABILITIES_TIMEOUT_MS
  • DANGEROUSLY_LOG_TO_SERVER_FOR_AI_AUTO_DEBUGGING

Flavor/internal markers

  • HAPPIER_SERVER_FLAVOR (alias: HAPPY_SERVER_FLAVOR)
    Runtime marker set by server startup; not typically user-set.

Proxmox VE

Deploy Happier Server on Proxmox VE using community-scripts helper scripts.

Server

Backend configuration, deployment notes, and authentication policies.

On this page

Canonical templateCore runtimeNetworking / reverse proxyAPI rate limitsStorage backendsLight flavor pathsBug reportsServer diagnostics snapshot controlsOAuth and authGlobal auth policyBuilt-in key-challenge login routeGitHub OAuthGitHub eligibility restrictionsAccount / terminal auth TTL controlsEncryption / plaintext storage (E2EE opt-out)Friends / socialVoiceUI/static servingBackground / maintenance jobsAdvanced / debug controlsFlavor/internal markers