HappierDocs

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.
  • The container entrypoint prefers a non-empty HAPPIER_SERVER_FLAVOR over HAPPY_SERVER_FLAVOR, then defaults to full. Prebuilt relay-server images set both to light; override HAPPIER_SERVER_FLAVOR=full and HAPPIER_DB_PROVIDER=postgres together for external Postgres. See the Kubernetes recipe.
  • Billing/subscription provider secrets are intentionally not documented on this page.

The server has many environment variables because it supports multiple storage/auth/networking topologies. Most deployments only need a small subset.

Required for most production deployments

  • HANDY_MASTER_SECRET Required for apps/server to protect server-managed secrets. Use a long random value and keep it stable across restarts.
  • DATABASE_URL (full flavor / external DB) Required when HAPPIER_DB_PROVIDER=postgres|mysql.
  • HAPPIER_DB_PROVIDER Pick your DB backend (postgres is the default in .env.example).
  • File storage settings for your chosen backend:
    • HAPPIER_FILES_BACKEND=local: no extra required env, or
    • HAPPIER_FILES_BACKEND=s3: requires S3_* credentials + S3_PUBLIC_URL

Strongly recommended (prevents pairing / mobile URL confusion)

  • HAPPIER_PUBLIC_SERVER_URL Canonical/share server URL embedded in QR codes/deep links and advertised via GET /v1/features. This should be the URL your phone can reach (ideally https://...).
  • HAPPIER_WEBAPP_URL (when self-hosting the web UI, or for OAuth return-to) Base URL for the web client and OAuth redirects. Optional if you use the hosted web app at https://cloud.happier.dev.

Recommended when behind a reverse proxy

  • HAPPIER_SERVER_TRUST_PROXY set to your proxy's specific address (Caddy/Nginx/Traefik), so the server uses X-Forwarded-* for request.ip and protocol detection only on connections from that proxy. See Networking / reverse proxy.

Nice-to-have

  • API rate limits: HAPPIER_API_RATE_LIMITS_* (recommended baseline is included below)
  • Metrics: METRICS_*

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) Any other value — including a typo — resolves to all rather than failing. worker refuses to start unless the Redis adapter is enabled (REDIS_URL plus HAPPIER_SOCKET_ADAPTER=redis-streams).
  • 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)

Logging

The format setting below is available in development source and is not yet verified in a published release.

  • HAPPIER_SERVER_LOG_LEVEL (fallbacks: HAPPIER_LOG_LEVEL, LOG_LEVEL; default info) Values: fatal | error | warn | info | debug | trace | silent. Any other value resolves to info.

  • HAPPIER_SERVER_LOG_FORMAT (default pretty) Values: pretty | json. Any other value resolves to pretty.

    • pretty: under Node, stdout carries colorized, multi-line pino-pretty output for terminals.
    • json: stdout carries pino's newline-delimited JSON, one object per log record. Use it when a collector such as Loki, Fluent Bit, or Vector parses container stdout.

    The Bun runtime always writes JSON, whatever this variable says. Consolidated debug logging keeps stdout enabled and also writes the existing debug file. Its startup notice goes to stderr so stdout remains parseable.

Networking / reverse proxy

  • HAPPIER_SERVER_TRUST_PROXY (optional) Controls which peers may set the client IP and protocol through X-Forwarded-* headers. The client IP keys IP-based rate limits and is used for public-link access records when consent logging is enabled. X-Real-IP alone does not override the client IP.

    • unset or false: never trust forwarded headers
    • a comma-separated list of your proxies' specific addresses (recommended), for example 127.0.0.1 for a proxy on the same host or 192.168.1.10: trust forwarded headers only on connections from those addresses. CIDRs and the names loopback, linklocal and uniquelocal are also supported (uniquelocal covers the private IPv4 ranges and fc00::/7). Use a CIDR or named range only when every peer in it is trusted to supply forwarded headers; a Docker subnet can include other containers that must not be trusted as proxies.
    • true: trust forwarded headers from any peer (only safe when every peer that can reach the server is trusted to supply them and trusted edge proxies sanitize incoming forwarded headers)

    A hop count such as 1 fails startup with a configuration error. A hop count cannot check who sent the headers, so any client that reaches the server directly could choose its own IP. Replace it with your proxy's address or CIDR. An entry that is not an address, CIDR or range name also fails startup.

Private certificate authorities on Android

Development source configures the Android app to trust both system CAs and CAs installed in the device's user certificate store. This change is not yet verified in a published release and requires a new native Android build; updating the relay server or applying a JavaScript-only app update cannot enable it in an older app.

For a private CA, install its CA certificate in Android's CA certificate store. Trust applies to the app's platform TLS connections, including HTTPS and WebSockets. Certificates must still have a valid chain and match the server hostname. The existing HAPPIER_ANDROID_USES_CLEARTEXT_TRAFFIC native build setting continues to control whether HTTP is allowed; trusting a CA does not change that setting.

HTTP response compression

Development builds negotiate Brotli or gzip for eligible API responses automatically. Direct deployments do not need a separate proxy compression rule for those responses. This is development behavior; do not assume it is present in an older stable server.

Existing proxy compression can stay enabled. Caddy and nginx skip responses that already carry Content-Encoding. Cloudflare can pass the origin encoding through or decompress and encode again for the visitor; it does not nest encodings. Preserve Content-Encoding and Vary through your proxy.

Static UI assets keep their precompressed-sidecar handling. Socket.IO polling and WebSocket compression remain separate from API response compression.

WebSockets (required for realtime + “machine online”)

Happier’s realtime sync (and machine presence) uses Socket.IO at:

  • GET /v1/updates (polling + websocket upgrade)

If your reverse proxy (or CDN) does not correctly forward WebSocket upgrades for /v1/updates, clients may appear to connect but machines will stay offline.

Common symptoms:

  • The UI/phone shows No online machines / “action required”
  • Server diagnostics includes machine.none_online
  • A daemon log shows “Connecting to …” but /v1/machines reports active: false

Nginx (example)

If you terminate TLS on Nginx, make sure it forwards websocket upgrades (either for all paths, or at least /v1/updates):

location /v1/updates/ {
  # Use the server's HTTP port (usually 3005; some managed/self-host flows use 53288).
  proxy_pass http://127.0.0.1:<port>;
  proxy_http_version 1.1;

  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";

  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Quick check (does the websocket upgrade work?)

From any machine that can reach your public HTTPS URL:

KEY="$(openssl rand -base64 16)"
curl -i -sS \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Version: 13" \
  -H "Sec-WebSocket-Key: $KEY" \
  "https://api.example.com/v1/updates/?EIO=4&transport=websocket" | head -n 5

Expected: HTTP/1.1 101 Switching Protocols.

Temporary workaround (daemon-side)

If you can’t fix the reverse proxy immediately, you can force the daemon to connect with polling first:

HAPPIER_SOCKET_TRANSPORTS=polling,websocket happier daemon restart --takeover
  • HAPPIER_PUBLIC_SERVER_URL Canonical/share URL for your server. Clients embed this in terminal-connect deep links and QR codes, and the server advertises it via GET /v1/features under capabilities.server.canonicalServerUrl.
    • Use the URL that works from your phone (prefer https://...).
    • If you intentionally run LAN-only, using http://<lan-ip>:3005 is fine, but QR/deep links will only work on the same LAN/VPN.
    • If this is unset, or if the active server URL resolves to loopback-only (localhost, 127.0.0.1, ::1, *.localhost), Happier may intentionally omit the server URL from mobile-oriented QR/deep links instead of embedding a broken address.
  • HAPPIER_WEBAPP_URL (alias: HAPPY_WEBAPP_URL) Base URL for the web client. The server advertises it via GET /v1/features under capabilities.server.webappUrl.
    • For the hosted web app: keep default https://cloud.happier.dev.
    • For self-hosted UI: set this to your UI origin (often the same as HAPPIER_PUBLIC_SERVER_URL).

User impact:

  • Add your phone
  • Restore account
  • CLI/mobile auth QR links
  • configure-server links

all work best when the embedded server URL is reachable from the target phone/device.

If users see a hint telling them to configure the phone’s server manually, that usually means the current server URL is loopback-only and cannot safely be shared cross-device.

Tailscale Serve inference (optional)

If HAPPIER_PUBLIC_SERVER_URL is unset and the server is exposed via tailscale serve, the server can best-effort infer the https://<machine>.<tailnet>.ts.net URL at boot.

  • HAPPIER_TAILSCALE_INFER_PUBLIC_URL (default true) Set to 0 to disable inference.
  • HAPPIER_TAILSCALE_BIN (default tailscale) Override the tailscale binary path/name.
  • HAPPIER_TAILSCALE_SERVE_STATUS_TIMEOUT_MS (default 750) Timeout for tailscale serve status probing (bounded to 1..10000).

API rate limits

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

Per-endpoint limits — all 33 of them, with defaults, what each counts against, and both environment variables — are on API rate limits, generated from the server's rate-limit catalog. The variable names are derived from endpoint ids at runtime, so they do not appear as literals anywhere in the source and are easy to miss when configuring a deployment by hand.

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)

Storage backends

  • S3_HOST
  • S3_PORT (optional)
  • S3_USE_SSL (true/false, default true)
  • S3_BUCKET
  • S3_PUBLIC_URL
  • S3_REGION (default us-east-1)
  • S3_ACCESS_KEY
  • S3_SECRET_KEY

S3 credentials from AWS web identity

This mode is under development and requires a server build containing the web identity change.

On AWS you can leave out S3_ACCESS_KEY and S3_SECRET_KEY and let the server assume an IAM role instead, for example with EKS IAM roles for service accounts (IRSA). The server switches to web identity only when both static keys are unset and these are present:

  • AWS_ROLE_ARN
  • AWS_WEB_IDENTITY_TOKEN_FILE
  • AWS_ROLE_SESSION_NAME (optional)
  • AWS_REGION (selects the regional STS endpoint)

The server exchanges the token for temporary credentials with STS AssumeRoleWithWebIdentity and fetches new ones shortly before they expire. Setting either static key keeps static-key mode, and then both are required. The other S3_* settings work the same in both modes. See S3 with an IAM role for a Kubernetes example.

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)

Light flavor SQLite

These apply when the light flavor generates its SQLite DATABASE_URL from the data directory. If you set DATABASE_URL yourself, put connection_limit and socket_timeout in that URL instead.

  • HAPPIER_SQLITE_CONNECTION_LIMIT (alias: HAPPY_SQLITE_CONNECTION_LIMIT, 1–64, default 1) Size of the server's SQLite connection pool. The default of one connection is deliberate. SQLite allows a single writer, and one connection queues the server's writes in order instead of making them compete for the database lock. The cost is that queries run one at a time, so a slow read (for example a large session list on a cold disk cache) delays the queries behind it. /ready does not wait behind them: it checks the database on its own connection. Raising the limit is an advanced override. Reads then run in parallel, but writes wait for each other inside SQLite for up to HAPPIER_SQLITE_BUSY_TIMEOUT_MS instead of queueing in order, and the synchronous and journal-size settings below apply to one connection only.
  • HAPPIER_SQLITE_BUSY_TIMEOUT_MS (alias: HAPPY_SQLITE_BUSY_TIMEOUT_MS, default 30000) How long a query waits for a lock held by another connection before failing. It is applied to every connection.
  • HAPPIER_SQLITE_SYNCHRONOUS (OFF | NORMAL | FULL | EXTRA, default NORMAL) and HAPPIER_SQLITE_JOURNAL_SIZE_LIMIT_BYTES (default 67108864) Applied once at startup, to one connection. With the default single connection that covers every query. With a larger pool, the other connections use SQLite's defaults (synchronous=FULL, no journal size limit).

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_DIAGNOSTICS_BUG_REPORT_SNAPSHOT_RATE_LIMIT_MAX (default 30)
  • HAPPIER_DIAGNOSTICS_BUG_REPORT_SNAPSHOT_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
  • HAPPIER_FEATURE_AUTH_RECOVERY__PROVIDER_RESET_ENABLED
  • HAPPIER_FEATURE_AUTH_UI__AUTO_REDIRECT_ENABLED
  • HAPPIER_FEATURE_AUTH_UI__AUTO_REDIRECT_PROVIDER_ID
  • HAPPIER_FEATURE_AUTH_UI__RECOVERY_KEY_REMINDER_ENABLED
  • AUTH_PROVIDERS_CONFIG_PATH
  • AUTH_PROVIDERS_CONFIG_JSON
  • AUTH_ACCOUNT_DISABLED_TTL_SECONDS

Legacy aliases (still accepted):

  • AUTH_RECOVERY_PROVIDER_RESET_ENABLED
  • AUTH_UI_AUTO_REDIRECT
  • AUTH_UI_AUTO_REDIRECT_PROVIDER_ID
  • AUTH_UI_RECOVERY_KEY_REMINDER_ENABLED

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).

Keyless OAuth login (optional)

Happier can use OAuth providers (GitHub/OIDC) as keyless login methods, meaning accounts can exist without device keys (intended for enterprise + plaintext storage deployments).

Keyless OAuth is gated by feature env vars:

  • HAPPIER_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED (default 0)
  • HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED (default 0)
  • HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS (CSV allowlist of provider ids, e.g. github,okta)
  • HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION (default 0)

Notes:

  • HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1 controls whether new keyless accounts can be created on first login.
  • Keyless auto-provisioning requires keyless accounts + plaintext defaults to be enabled (see Server Auth for the current prerequisites).

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://cloud.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.

mTLS auth (enterprise)

For full setup guidance, see Server → mTLS Auth.

  • HAPPIER_FEATURE_AUTH_MTLS__ENABLED (default 0)
  • HAPPIER_FEATURE_AUTH_MTLS__MODE (forwarded | direct)
  • HAPPIER_FEATURE_AUTH_MTLS__AUTO_PROVISION (default 0)
  • HAPPIER_FEATURE_AUTH_MTLS__IDENTITY_SOURCE (san_email | san_upn | subject_cn | fingerprint)
  • HAPPIER_FEATURE_AUTH_MTLS__ALLOWED_EMAIL_DOMAINS (CSV)
  • HAPPIER_FEATURE_AUTH_MTLS__ALLOWED_ISSUERS (CSV; comma/newline separated issuer values; compared against the issuer CN extracted from the forwarded issuer string)
  • HAPPIER_FEATURE_AUTH_MTLS__TRUST_FORWARDED_HEADERS (default 0)
  • HAPPIER_FEATURE_AUTH_MTLS__FORWARDED_EMAIL_HEADER
  • HAPPIER_FEATURE_AUTH_MTLS__FORWARDED_UPN_HEADER
  • HAPPIER_FEATURE_AUTH_MTLS__FORWARDED_SUBJECT_HEADER
  • HAPPIER_FEATURE_AUTH_MTLS__FORWARDED_FINGERPRINT_HEADER
  • HAPPIER_FEATURE_AUTH_MTLS__FORWARDED_ISSUER_HEADER
  • HAPPIER_FEATURE_AUTH_MTLS__RETURN_TO_ALLOW_PREFIXES (CSV)
  • HAPPIER_FEATURE_AUTH_MTLS__CLAIM_TTL_SECONDS

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

Plaintext at-rest sealing (plaintext/keyless accounts only; DB storage):

  • HAPPIER_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_SETTINGS_AT_REST (default server_sealed) Values: none | server_sealed
  • HAPPIER_FEATURE_ENCRYPTION__PLAIN_ACCOUNT_CREDENTIALS_AT_REST (default server_sealed) Values: none | server_sealed

Session Agent switching

  • HAPPIER_FEATURE_SESSIONS_AGENT_SWITCHING__ENABLED (default 1)

This is an opt-out: in-place Agent switching is advertised unless it is explicitly disabled. For what the feature does, see Continue with another Agent.

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
  • HAPPIER_VOICE_TOKEN_RATE_LIMIT_MAX
  • HAPPIER_VOICE_TOKEN_RATE_LIMIT_WINDOW
  • HAPPIER_VOICE_SESSION_COMPLETE_RATE_LIMIT_MAX
  • HAPPIER_VOICE_SESSION_COMPLETE_RATE_LIMIT_WINDOW
  • HAPPIER_SERVER_RETENTION__VOICE_SESSION_LEASES__MODE
  • HAPPIER_SERVER_RETENTION__VOICE_SESSION_LEASES__DAYS
  • 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

Voice-lease and account-change cleanup used to be standalone jobs with their own variables. They are now domains of the retention worker, so they are configured the same way as every other retained table — see Server retention policies for the full domain list and the global knobs that bound a sweep.

  • HAPPIER_SERVER_RETENTION__ACCOUNT_CHANGES__MODE
  • HAPPIER_SERVER_RETENTION__ACCOUNT_CHANGES__DAYS
  • HAPPY_PRESENCE_STREAM_MAXLEN

Feature gates

Each of these decides whether the server advertises a capability at all. They default to on: a client still has to enable the matching toggle, and several are experimental there, so leaving these alone is the normal case. Set one to 0 when you want a capability unavailable on your deployment regardless of what a client asks for.

The full catalogue of gated capabilities, including the ones with no environment variable, is on Feature flags.

  • HAPPIER_FEATURE_ATTACHMENTS_UPLOADS__ENABLED (default 1)
  • HAPPIER_FEATURE_AUTOMATIONS__ENABLED (default 1)
  • HAPPIER_FEATURE_AUTH_PAIRING__DESKTOP_QR_MOBILE_SCAN_ENABLED (default 1)
  • HAPPIER_FEATURE_CHANNEL_BRIDGES__ENABLED (default 1)
  • HAPPIER_FEATURE_CHANNEL_BRIDGES_TELEGRAM__ENABLED (default 1)
  • HAPPIER_FEATURE_CONNECTED_SERVICES_ACCOUNT_GROUPS__ENABLED (default 1) — account pools
  • HAPPIER_FEATURE_CONNECTED_SERVICES_ACCOUNT_FALLBACK__ENABLED (default 1)
  • HAPPIER_FEATURE_SESSIONS_DRAFTS__ENABLED (default 1) — synchronized existing- and new-Session drafts
  • HAPPIER_FEATURE_SESSIONS_FOLDERS__ENABLED (default 1)
  • HAPPIER_FEATURE_SESSIONS_HANDOFF__ENABLED (default 1)
  • HAPPIER_FEATURE_SESSIONS_USAGE_LIMIT_RECOVERY__ENABLED (default 1)
  • HAPPIER_FEATURE_TERMINAL_EMBEDDED_PTY__ENABLED (default 1)
  • HAPPIER_FEATURE_UPDATES_OTA__ENABLED (default 1)

Machine-to-machine transfers

  • HAPPIER_FEATURE_MACHINES_TRANSFER_DIRECT_PEER__ENABLED (default 1)
  • HAPPIER_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__ENABLED (default 1)
  • HAPPIER_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__MAX_BYTES (hard ceiling 8 GiB)
  • HAPPIER_FEATURE_MACHINES_TRANSFER_SERVER_ROUTED__MAX_ACTIVE_TRANSFERS_PER_SOCKET (default 128; min 1, max 10000)

Pet package limits

Pet syncing is off by default (HAPPIER_FEATURE_PETS_SYNC__ENABLED). These bound what an account can import once it is on:

  • HAPPIER_FEATURE_PETS_SYNC__MAX_MANIFEST_BYTES (default 16384)
  • HAPPIER_FEATURE_PETS_SYNC__MAX_CANONICAL_SPRITESHEET_BYTES (default 5242880)
  • HAPPIER_FEATURE_PETS_SYNC__MAX_CANONICAL_PACKAGE_BYTES (default 6291456)
  • HAPPIER_FEATURE_PETS_SYNC__MAX_IMPORTED_PETS_PER_ACCOUNT (default 20)
  • HAPPIER_FEATURE_PETS_SYNC__MAX_IMPORTED_PET_BYTES_PER_ACCOUNT (default 104857600)
  • HAPPIER_FEATURE_PETS_SYNC__ENCRYPTED_CUSTOM_PET_SYNC_POLICY

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.

On this page