Skip to content

Configuration Reference ​

Every environment variable and settings.json key that HAPI reads, grouped by the process that reads it. For a quick start, the defaults are enough; see Installation for the common setup and Authentication for tokens and passkeys.

How configuration is resolved ​

HAPI keeps its state in one directory, ~/.hapi by default (override with HAPI_HOME). The hub and the CLI on the same machine share settings.json in that directory.

~/.hapi/
├── settings.json        # Configuration (hub + CLI)
├── hapi.db              # SQLite database (hub)
├── jwt-secret.json      # Web/native JWT signing key (hub)
├── owner-id.json        # Hub owner id (hub)
├── runner.state.json    # Runner process state
└── logs/                # Log files

Priority is environment variable > settings.json > default.

  • Hub settings with a settings.json key in the tables below are saved to settings.json the first time the hub sees them in the environment, if the key is not already present. Later environment changes still win at runtime, but the saved value stays in the file.
  • CLI settings (apiUrl, extraHeaders) are never saved from the environment. cliApiToken is saved by hapi auth login or the first-run prompt.
  • Changes take effect on the next start of the process that reads them. Restart the hub or runner (hapi runner start replaces a running runner) after editing.

Editors that support JSON Schema can validate the file:

json
{
  "$schema": "https://hapi.run/docs/schemas/settings.schema.json",
  "listenHost": "0.0.0.0",
  "publicUrl": "https://hapi.example.com"
}

What is listed here. This page covers variables an operator can reasonably set. It omits variables that HAPI sets for its own child processes (runner handoff and launcher PIDs, HAPI_INVOKED_CWD, hook ports/tokens, HAPI_DISCLAIM_*, HAPI_CLI_EXECUTABLE, HAPI_BUN_EXEC, tunnel-client TUNWG_*), test-only variables, and the native variables of each agent (CLAUDE_CONFIG_DIR, CODEX_HOME, OPENCODE_CONFIG, provider API keys, …), which HAPI passes through to the agent unchanged.

Hub ​

Read by hapi hub (alias hapi server).

Network and identity ​

Variablesettings.jsonDefaultDescription
HAPI_HOME–~/.hapiData directory. A leading ~ is expanded.
DB_PATH–$HAPI_HOME/hapi.dbSQLite database path.
CLI_API_TOKENcliApiTokenGenerated on first runBase access token. Must not contain :; the hub refuses to start otherwise. See Authentication.
HAPI_LISTEN_HOSTlistenHost127.0.0.1HTTP bind address. Also set by hapi hub --host.
HAPI_LISTEN_PORTlistenPort3006HTTP port. Also set by hapi hub --port.
HAPI_PUBLIC_URLpublicUrlhttp://localhost:<port>Public URL of the hub. Must be the canonical HTTPS origin (no path) for passkeys; also used by the Telegram Mini App and to derive default CORS origins.
CORS_ORIGINScorsOriginsOrigin of publicUrlComma-separated allowed origins, or *. A separately hosted web app needs its exact origin here for passkey callbacks.
HAPI_PASSKEY_NATIVE_ORIGINS––Extra trusted Android app origins for native passkeys, comma-separated, each android:apk-key-hash:<hash>. Only needed for custom-signed Android builds; any other form stops the hub from starting.

Relay tunnel ​

Used only with hapi hub --relay. See Deployment.

Variablesettings.jsonDefaultDescription
HAPI_RELAY_API–relay.hapi.runRelay API domain.
HAPI_RELAY_AUTHrelayAuthKeyIssued by the relayRelay key override. The issued key is stored as relayAuthKey automatically; set the variable only when an operator gave you a key.
HAPI_RELAY_FORCE_TCP–falsetrue or 1 forces TCP when UDP is blocked.
HAPI_OFFICIAL_WEB_URL–https://app.hapi.runWeb app origin added to CORS when the relay is enabled.

Notifications ​

See Notifications for setup.

Variablesettings.jsonDefaultDescription
TELEGRAM_BOT_TOKENtelegramBotToken–Telegram bot token. Enables the bot, Mini App sign-in and Telegram notifications.
TELEGRAM_NOTIFICATIONtelegramNotificationtrueEnable Telegram notifications. In the environment, any value other than true disables.
SERVERCHAN_SENDKEYserverChanSendKey–ServerChan (Server酱) SendKey.
SERVERCHAN_NOTIFICATIONserverChanNotificationtrueEnable ServerChan notifications. In the environment, any value other than true disables.
SERVERCHAN_BACKGROUND_ONLYserverChanBackgroundOnlyfalseOnly send when no visible HAPI client is connected in the namespace.
VAPID_SUBJECT–mailto:[email protected]Web Push contact. VAPID keys are generated into vapidKeys.
HAPI_ANDROID_PUSHandroidPushModeautoauto (direct FCM when fcmServiceAccountPath is set, otherwise the push relay), relay, fcm, or off. Unknown values disable Android push.
FCM_SERVICE_ACCOUNT_PATHfcmServiceAccountPath–Firebase service-account JSON for private builds of the Android app.
HAPI_IOS_PUSHiosPushModerelayrelay, apns (direct), or off.
HAPI_PUSH_RELAY_URLiosPushRelayUrlhttps://push.hapi.runNative push relay for both Android and iOS. Unrelated to --relay.
APNS_KEY_P8_PATH, APNS_KEY_ID, APNS_TEAM_ID, APNS_BUNDLE_IDapnsKeyP8Path, apnsKeyId, apnsTeamId, apnsBundleId–Required for HAPI_IOS_PUSH=apns; iOS push is disabled if any is missing.
APNS_ENVapnsEnvproductionproduction or sandbox for direct APNs.
HAPI_NOTIFY_DEBUG––1 logs push delivery decisions.

Voice and dictation ​

Provider keys can also be entered in the web app under Settings → Voice, which stores them in providerCredentials. A variable set when the hub starts wins and cannot be edited from Settings. See Voice Assistant.

VariableDefaultDescription
ELEVENLABS_API_KEY–ElevenLabs voice assistant and dictation.
ELEVENLABS_AGENT_IDCreated automaticallyUse an existing ElevenLabs agent.
ELEVENLABS_VOICE_AGENT_MAP–JSON object mapping voice ids to ElevenLabs agent ids.
ELEVENLABS_MAX_DURATION_SECONDS1800Maximum length of one conversation, 60–7200. Also editable in Settings (elevenLabsMaxDurationSeconds) when the variable is unset.
GEMINI_API_KEY / GOOGLE_API_KEY–Gemini Live voice assistant.
GEMINI_API_BASEGoogle defaultGemini API base URL handed to the web client.
GEMINI_LIVE_WS_URLGoogle defaultUpstream Live WebSocket URL used by the hub's Gemini proxy.
DASHSCOPE_API_KEY / QWEN_API_KEY–Qwen Realtime voice assistant.
QWEN_REALTIME_WS_URLDashScope defaultUpstream Qwen Realtime WebSocket URL used by the hub's proxy.
VOICE_BACKENDFirst configured backendPreferred assistant: elevenlabs, gemini-live, or qwen-realtime.
OPENAI_API_KEY–OpenAI dictation.
DEEPGRAM_API_KEY–Deepgram dictation.
GROQ_API_KEY–Groq dictation.
TRANSCRIPTION_BASE_URL, TRANSCRIPTION_MODEL, TRANSCRIPTION_API_KEY–OpenAI-compatible or local transcription endpoint, model, and optional bearer token.

Generated session titles ​

All three HAPI_TITLE_PROVIDER_* connection variables are required to enable the Generate action in the session rename dialog. The key is never sent to the browser. Each request sends recent visible conversation text (up to 200 messages, bounded in size) to the configured provider.

With a provider configured, the hub also makes one best-effort automatic request after the first completed turn when the session has no name or summary yet. Failures are ignored and the attempt is remembered across restarts; Generate stays available to retry. A manual or agent-set title that arrives meanwhile takes precedence. Without a provider, titles behave as before.

VariableDefaultDescription
HAPI_TITLE_PROVIDER_BASE_URL–OpenAI-compatible Chat Completions base URL.
HAPI_TITLE_PROVIDER_API_KEY–API key for that provider.
HAPI_TITLE_PROVIDER_MODEL–Model id, preferably a small one.
HAPI_TITLE_PROVIDER_MAX_TOKENS64Completion-token budget per title; raise for reasoning models.
HAPI_TITLE_PROVIDER_TIMEOUT_MS10000Request timeout.
HAPI_TITLE_SUGGESTION_RATE_LIMIT5Suggestions per session per window.
HAPI_TITLE_SUGGESTION_RATE_WINDOW_MS600000Rate-limit window.

Sessions, uploads and terminals ​

VariableDefaultDescription
HAPI_SESSION_IDLE_TIMEOUT_MS43200000 (12 h)A session that sends only keep-alives for this long, with no visible work or pending request, is shown as idle. 0 disables.
HAPI_MAX_UPLOAD_BYTES536870912 (512 MiB)Maximum size of one uploaded file; capped at 10 GiB. The machine that receives the file checks the same variable, so set it on the hub and the CLI/runner.
HAPI_SCRATCHLIST_MAX_ATTACHMENT_BYTES_PER_FILE10485760 (10 MiB)Scratchlist attachment limit per file.
HAPI_SCRATCHLIST_MAX_ATTACHMENTS_PER_ENTRY4Attachments per scratchlist entry.
HAPI_SCRATCHLIST_MAX_ATTACHMENT_BYTES_PER_ENTRY20971520 (20 MiB)Total attachment size per entry.
HAPI_SCRATCHLIST_MAX_ATTACHMENT_BYTES_PER_SESSION104857600 (100 MiB)Total attachment size per session.
HAPI_SCRATCHLIST_ALLOWED_ATTACHMENT_MIMESJPEG, PNG, GIF, WebP, SVG, PDF, plain textComma-separated MIME allowlist.
HAPI_TERMINAL_IDLE_TIMEOUT_MS900000 (15 min)Close idle web terminals. Read by both the hub and the CLI/runner that hosts the terminal.
HAPI_TERMINAL_MAX_TERMINALS4Maximum concurrent web terminals. Read by both the hub and the CLI/runner.
HAPI_CURSOR_LEGACY_AUTO_MIGRATEOn0, false, no or off stops the hub from migrating legacy Cursor sessions to ACP when they are resumed.
HAPI_HOSTNAMEOS host nameHost name the hub treats as its own when deciding whether a legacy Cursor session is local.

Codex Desktop integration ​

Only needed for the Codex Desktop session import and restart actions.

VariableDefaultDescription
HAPI_CODEX_COMMANDcodex on PATHCodex launcher used to detect an installation.
HAPI_CODEX_APP_PATH/Applications/Codex.app, ~/Applications/Codex.appCodex Desktop app path on macOS.
HAPI_CODEX_SCRIPT_ROOTHub working directoryDirectory containing helper scripts.
HAPI_CODEX_RESTART_SCRIPTRestart-CodexDesktop.ps1 in the script rootPowerShell restart script.
HAPI_CODEX_WORKSPACEScript directoryWorkspace for script logs and direct import.
HAPI_CODEX_SCRIPT_TIMEOUT_MS60000Script timeout.
HAPI_PWSH_PATHpwsh, then powershell.exePowerShell executable.

Hub-managed settings ​

These keys have no environment variable. Change them from the web app's Settings page; the hub writes them to settings.json.

KeyDefaultDescription
peerSpawnDefaults{ "agent": "claude", "permissionMode": "yolo", "models": { "claude": "sonnet" } }Defaults for spawn_peer and hapi spawn-peer. Each field is optional.
sessionSummaryContractfalseAsk supported agents to end turns with an AGENT_NOTIFY_SUMMARY line used by notifications.
sessionSummaryInChatfalseShow that summary line as a compact row in chat instead of hiding it.
autoBridgeTransientModelErrorsfalseAfter a transient model error, Cursor sessions automatically queue one retry.
providerCredentials–Voice and dictation keys saved from Settings.
elevenLabsMaxDurationSeconds1800See ELEVENLABS_MAX_DURATION_SECONDS.
vapidKeysGeneratedWeb Push keys. Do not edit.

CLI ​

Read by hapi, hapi <agent>, and the other client commands on every machine that connects to a hub.

Variablesettings.jsonDefaultDescription
HAPI_API_URLapiUrlhttp://localhost:3006Hub URL. Settings also accepts the legacy key serverUrl.
CLI_API_TOKENcliApiTokenPrompted on first interactive runAccess token, optionally with :<namespace>. Saved by hapi auth login. Non-interactive runs fail if it is missing.
HAPI_EXTRA_HEADERS_JSONextraHeaders–JSON object of extra headers for CLI → hub HTTP and WebSocket requests, for example an access-proxy cookie.
HAPI_HOME–~/.hapiData directory. Use one per namespace when a machine serves several.
HAPI_API_FALLBACK_URLS––Comma-separated alternative URLs for the same hub (for example LAN and tunnel addresses). The machine connection rotates to the next URL after repeated connect failures and retries the primary after 30 minutes.
HAPI_API_FAILOVER_AFTER–5Consecutive connect failures before rotating to the next URL.
HAPI_HOSTNAME–OS host nameHost name reported for the machine and its sessions.
HAPI_HTTP_MCP_URL––Target for hapi mcp when --url is not given.
HAPI_WAIT_ACTIVE_SECS–60Default --wait for hapi spawn-peer.
HAPI_SESSION_SUMMARY_CONTRACT–Hub settingOverrides sessionSummaryContract for sessions started by this process. 0, false, off or no disables; any other non-empty value enables.
HAPI_DISABLE_PEER_TOOLS––1, true or yes removes the peer tools (list_peers, inspect_peer, ping_peer, spawn_peer) from wrapped agents and makes the peer CLI commands fail. Usually set on the runner. See Installation.
HAPI_TERMINAL_SHELLPowerShell 7, Windows PowerShell, then cmd.exeWindows only: shell for web terminals. On macOS and Linux, web terminals use $SHELL, falling back to /bin/zsh (macOS) or /bin/bash.
HAPI_EXPERIMENTAL––Reserved flag (true, 1, yes); no current feature depends on it.
DEBUG––Any value enables verbose logs and stack traces.

HAPI_MAX_UPLOAD_BYTES, HAPI_TERMINAL_IDLE_TIMEOUT_MS and HAPI_TERMINAL_MAX_TERMINALS are also read here; see the hub table.

Other settings.json keys written by the CLI:

KeyDescription
machineId, machineIdConfirmedByServerMachine identity, created on first connection. Cleared by hapi auth logout. Do not edit.
runnerAutoStartWhenRunningHappyLegacy key; no longer read.

Runner ​

Read by hapi runner start / start-sync. The runner also reads every CLI variable. Its spawned sessions inherit its environment, so set agent variables on the runner too. hapi runner start replaces a running runner so new values take effect.

VariableDefaultDescription
HAPI_RUNNER_SUPERVISED–Exactly 1 tells the hub that a supervisor (systemd, launchd, pm2) restarts the runner after it exits, enabling the web Restart control. Set only when that is true.
HAPI_DISABLE_VERSION_HANDOFF–Exactly 1 disables automatic runner replacement when the installed CLI binary changes. Use when a supervisor manages upgrades.
HAPI_RUNNER_HEARTBEAT_INTERVAL60000Heartbeat interval in ms (version checks, dead-session pruning).
HAPI_RUNNER_HTTP_TIMEOUT10000Timeout in ms for local runner control requests.
HAPI_RUNNER_WEBHOOK_TIMEOUT_MS15000 (Codex: 30000)How long a spawn waits for the new session to report in. Raise for slow agent startup.

Agent-specific ​

Set these on the machine that runs the agent: your shell for terminal sessions, the runner for remote spawns.

VariableAgentDefaultDescription
HAPI_CLAUDE_PATHClaude Codeclaude on PATHPath to the claude executable.
CLAUDE_REMOTE_RESPAWN_BACKOFF_MSClaude Code1000Delay before respawning a failed remote-mode Claude process.
HAPI_CODEX_APP_SERVER_BINCodexcodexCommand used to start codex app-server for remote sessions.
HAPI_CODEX_MODEL_CATALOG_JSONCodex–Absolute path (or ~/…) to a static Codex model catalog, passed as -c model_catalog_json=….
HAPI_CODEX_LAZY_HISTORY_IDSCodex–Comma-separated native thread ids that load only their newest turn. For exceptionally large threads; set on the runner.
COPILOT_CLI_PATHGitHub CopilotcopilotPath to the Copilot CLI.
CURSOR_LEGACY_TRANSIENT_BACKOFF_MSCursor (legacy)2000Delay before retrying after a transient Cursor Agent error.
HAPI_DSH_ACP_COMMANDDeepSeek Harnessdsh (with --profile acp)ACP server executable.
HAPI_DSH_ACP_ARGS_JSONDeepSeek Harness–JSON array of ACP server arguments.
HAPI_DSH_ACP_CONFIGDeepSeek Harness–Absolute config path for the ACP server.

See Supported Agents for installing and authenticating each agent.

Set by HAPI inside sessions ​

HAPI exports these into agent processes. Read them from scripts; do not set them yourself.

VariableDescription
HAPI_SESSION_IDThe current HAPI session id, for example for hapi job.
HAPI_API_URLExported only when a non-default hub URL is configured. CLI_API_TOKEN from settings.json is not copied into agent environments.
HAPI_WORKTREE_BASE_PATH, HAPI_WORKTREE_BRANCH, HAPI_WORKTREE_NAME, HAPI_WORKTREE_PATH, HAPI_WORKTREE_CREATED_ATSet for sessions created as a worktree.

Released under the AGPL-3.0 License. · Privacy Policy