hapi/docs/guide/installation.md

Installation

Install the HAPI CLI and set up the hub. To install the paid phone apps and pair them, see Native apps (iOS / Android); for the free browser client, see PWA.

Prerequisites

• At least one supported agent CLI installed (Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, DeepSeek Harness ACP server, and more — see Supported Agents)

Verify your CLI is installed:

# For Claude Code
claude --version

# For OpenAI Codex CLI
codex --version

# For Cursor Agent CLI
agent --version

# For Grok Build CLI
grok --version

# For OpenCode CLI
opencode --version

Architecture

HAPI uses these runtime roles:

Component	Role	Required
CLI	Wraps AI coding agents, runs sessions	Yes
Hub	Central coordinator: persistence, real-time sync, remote access	Yes
Runner	Background service for remote session spawning	Optional
Client	Native iOS/Android, Web/PWA or Telegram Mini App	One client for remote control

How they work together

The CLI and Runner connect to the hub over Socket.IO; clients send actions through REST and receive live updates through SSE. The Runner spawns CLI sessions when requested through the hub. See the architecture overview.

• CLI: Choose an agent with hapi, or start one directly with hapi <agent>. The CLI wraps your AI agent and syncs with the hub. Scripts must specify the agent explicitly.
• Hub: Run hapi hub. Stores sessions, handles permissions, enables remote access.
• Runner: Run hapi runner start. Lets you spawn sessions from native or web clients without keeping a terminal open.
• Client: Pair a native app with the HTTPS hub origin and access token, or log in through the web app.

Typical workflows

Local only: hapi hub → hapi → work in terminal

Remote access: hapi hub --relay → hapi runner start → pair a native app or open the web app

Install the CLI

npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org

Recommendation: use the official npm registry for global install. Some mirrors may not sync platform packages in time.

Or with Homebrew:

brew install tiann/tap/hapi

Upgrades that still run an older version

The @twsxtd/hapi package is a launcher. Its platform binary (for example, @twsxtd/hapi-darwin-arm64) is an optional dependency pinned to the same version. If a mirror has the new launcher but not the matching platform package, the package manager can finish upgrading the launcher while skipping the binary. A previous binary may remain installed. Older launchers can silently run it; launchers with version validation instead report a version mismatch.

Retry against the official registry using your existing package manager. For Bun:

bun remove -g @twsxtd/hapi && bun add -g @twsxtd/hapi@latest --registry=https://registry.npmjs.org
hapi --version

Removing the launcher first clears its dependency resolution; --force alone can leave a previously skipped platform package out of Bun's lockfile. This does not remove your HAPI settings or sessions. To stay on a specific release, replace latest with that version. For npm, use npm install -g @twsxtd/hapi@latest --registry=https://registry.npmjs.org. If the command still reports an old version, check for another HAPI installation earlier on PATH. Restart an already-running hub or runner after upgrading; installing a new binary does not replace running processes.

Other install options

npx (no install)

npx @twsxtd/hapi

Prebuilt binary

Download the latest release from GitHub Releases.

xattr -d com.apple.quarantine ./hapi
chmod +x ./hapi
sudo mv ./hapi /usr/local/bin/

Build from source

Requires Bun 1.4.4.

git clone https://github.com/tiann/hapi.git
cd hapi
bun install
bun build:single-exe

./cli/dist-exe/<target>/hapi

<target> is the Bun build target (e.g., bun-linux-x64, bun-darwin-arm64); it defaults to the host platform and architecture.

Hub setup

The hub can be deployed on:

• Local desktop (default) - Run on your development machine
• Remote host - Deploy the hub on a VPS, cloud host, or any machine with network access

Default: Public Relay (recommended)

hapi hub --relay

The terminal displays a URL and QR code. Scan to access from anywhere.

hapi server remains supported as an alias.

• End-to-end encrypted with WireGuard + TLS
• No configuration needed
• Works behind NAT, firewalls, and any network

For relay key management, TCP fallback, and self-hosted tunnel alternatives, see Deployment.

Local Only

hapi hub
# or
hapi hub --no-relay

The hub listens on http://localhost:3006 by default.

On first run, HAPI:

1. Creates ~/.hapi/
2. Generates a secure access token
3. Prints the token and saves it to ~/.hapi/settings.json

Config files

~/.hapi/
├── settings.json      # Main configuration
├── hapi.db           # SQLite database (hub)
├── runner.state.json  # Runner process state
└── logs/             # Log files

Environment variables

Variable	Default	settings.json	Description
CLI_API_TOKEN	Auto-generated	cliApiToken	Shared secret for authentication
HAPI_API_URL	http://localhost:3006	apiUrl	Hub URL for CLI connections
HAPI_EXTRA_HEADERS_JSON	-	extraHeaders	JSON object of extra outbound headers for CLI → hub HTTP/WebSocket requests
HAPI_LISTEN_HOST	127.0.0.1	listenHost	Hub HTTP bind address
HAPI_LISTEN_PORT	3006	listenPort	Hub HTTP port
HAPI_PUBLIC_URL	-	publicUrl	Public URL for external access
CORS_ORIGINS	-	corsOrigins	Allowed CORS origins (comma-separated)
TELEGRAM_BOT_TOKEN	-	telegramBotToken	Telegram Bot API token
TELEGRAM_NOTIFICATION	true	telegramNotification	Enable Telegram notifications
SERVERCHAN_SENDKEY	-	serverChanSendKey	Server酱 (ServerChan) SendKey for push notifications
SERVERCHAN_NOTIFICATION	true	serverChanNotification	Enable ServerChan notifications
SERVERCHAN_BACKGROUND_ONLY	false	serverChanBackgroundOnly	Only send ServerChan notifications when no visible HAPI connection exists in the namespace
HAPI_RELAY_API	relay.hapi.run	-	Relay API domain for the public relay
HAPI_RELAY_AUTH	Per-hub key issued by the relay	relayAuthKey	Relay auth key override (set only when an operator provides a key)
HAPI_RELAY_FORCE_TCP	false	-	Force TCP mode for relay
HAPI_OFFICIAL_WEB_URL	https://app.hapi.run	-	Official web app origin, added to CORS when the relay is enabled
VAPID_SUBJECT	mailto:admin@hapi.run	-	Web Push contact info
HAPI_ANDROID_PUSH	auto	androidPushMode	Android push: official relay by default, direct FCM when private credentials are configured; also accepts relay, fcm, off
HAPI_IOS_PUSH	relay	iosPushMode	iOS push: relay, direct apns, or off
HAPI_PUSH_RELAY_URL	https://push.hapi.run	iosPushRelayUrl	Shared Android/iOS push relay, independent of the network tunnel
FCM_SERVICE_ACCOUNT_PATH	-	fcmServiceAccountPath	Direct FCM credentials for private builds using the same Firebase project
HAPI_HOME	~/.hapi	-	Config directory path
DB_PATH	~/.hapi/hapi.db	-	Database file path
HAPI_EXPERIMENTAL	-	-	CLI: enable experimental features (true/1/yes)
ELEVENLABS_API_KEY	-	Settings / env	ElevenLabs API key for voice + dictation
ELEVENLABS_AGENT_ID	Auto-created	-	Custom ElevenLabs agent ID
ELEVENLABS_MAX_DURATION_SECONDS	1800	-	Max length of one ElevenLabs voice conversation (60-7200)
GEMINI_API_KEY / GOOGLE_API_KEY	-	Settings / env	Gemini Live voice assistant
DASHSCOPE_API_KEY / QWEN_API_KEY	-	Settings / env	Qwen Realtime voice assistant
VOICE_BACKEND	Auto-detected	-	Default assistant backend: elevenlabs, gemini-live, or qwen-realtime
OPENAI_API_KEY	-	Settings / env	OpenAI API key for dictation (gpt-transcribe / gpt-live-transcribe)
DEEPGRAM_API_KEY	-	Settings / env	Deepgram API key for dictation (nova-3)
GROQ_API_KEY	-	Settings / env	Groq API key for dictation (whisper-large-v3)
TRANSCRIPTION_BASE_URL	-	Settings / env	OpenAI-compatible/local transcription base URL
TRANSCRIPTION_MODEL	-	Settings / env	Model for the OpenAI-compatible transcription endpoint
TRANSCRIPTION_API_KEY	-	Settings / env	Optional bearer token for that endpoint
HAPI_TITLE_PROVIDER_BASE_URL	-	-	Server-only OpenAI-compatible Chat Completions base URL for generated session titles
HAPI_TITLE_PROVIDER_API_KEY	-	-	Server-only API key for generated session titles; never sent to the browser
HAPI_TITLE_PROVIDER_MODEL	-	-	Server-only lightweight model used for generated session titles
HAPI_TITLE_SUGGESTION_RATE_LIMIT	5	-	Maximum title suggestions per session in the rate-limit window
HAPI_TITLE_SUGGESTION_RATE_WINDOW_MS	600000	-	Title suggestion rate-limit window in milliseconds
HAPI_TITLE_PROVIDER_MAX_TOKENS	64	-	Maximum completion-token budget per generated title; raise for reasoning-model providers
HAPI_TITLE_PROVIDER_TIMEOUT_MS	10000	-	Title provider request timeout in milliseconds

The session rename dialog's Generate action is unavailable until all three HAPI_TITLE_PROVIDER_* variables are configured on the Hub. The provider is used by the automatic fallback below and the manual Generate action. The existing manual rename flow does not require these variables. Each request sends recent visible user/assistant conversation text (up to 200 stored messages and a bounded prompt) to that configured provider.

When a provider is configured, the Hub also makes one best-effort automatic request after the first completed turn if the session has no manual name or existing summary. Automatic failures are ignored and do not affect the primary conversation. The manual Generate action remains available for retrying after an automatic failure. An attempt is remembered across Hub restarts, so later turns do not silently retry it. A manual or Agent title arriving during generation takes precedence. Without a configured provider, existing title behavior is unchanged.

settings.json example

Configuration priority: ENV > settings.json > default

When ENV values are set and not present in settings.json, they are automatically saved. HAPI_EXTRA_HEADERS_JSON is not automatically saved, so access credentials are not persisted unexpectedly.

{
  "$schema": "https://hapi.run/docs/schemas/settings.schema.json",
  "listenHost": "0.0.0.0",
  "listenPort": 3006,
  "publicUrl": "https://your-domain.com",
  "extraHeaders": {
    "Cookie": "CF_Authorization=..."
  }
}

JSON Schema: settings.schema.json

CLI setup

If the hub is not on localhost, set these before running hapi:

export HAPI_API_URL="http://your-hub:3006"
export CLI_API_TOKEN="your-token-here"
export HAPI_EXTRA_HEADERS_JSON='{"Cookie":"CF_Authorization=..."}'

Or use interactive login:

hapi auth login

Authentication commands:

hapi auth status
hapi auth login
hapi auth logout

Each machine gets a unique ID stored in ~/.hapi/settings.json. This allows:

• Multiple machines to connect to one hub
• Remote session spawning on specific machines
• Machine health monitoring

Diagnostics

Run hapi doctor for a full diagnostics report: configuration, runner status, logs, and relevant environment info.

hapi doctor          # Diagnostics report
hapi doctor clean    # Kill runaway hapi processes

Runner setup

Run a background service for remote session spawning:

hapi runner start
hapi runner status
hapi runner logs
hapi runner stop

With the runner running:

• Your machine appears in the "Machines" list
• You can spawn sessions remotely from the web app
• Sessions persist even when the terminal is closed

Split hub + remote runner (peer discovery)

When the hub runs on one host and the runner on another, agents inside runner-spawned sessions should discover peers via MCP list_peers (same hub credentials as the session CLI). Prefer that over shelling hapi ping-peer --list.

[Hub host]  hapi hub          ← sessions DB + /api/sessions
     ▲
     │ HAPI_API_URL + CLI_API_TOKEN
     │
[Runner host]  hapi runner start  → spawns session CLIs
                     │
                     ▼
              agent session  → MCP list_peers / inspect_peer / ping_peer / spawn_peer

On the runner host, configure the same hub URL and token the hub uses:

export HAPI_API_URL="http://your-hub:3006"   # or Tailscale / public URL
export CLI_API_TOKEN="your-token-here"
# or: hapi auth login   # saves the token; still set HAPI_API_URL for a remote hub
hapi runner start

Session CLI may export an explicit non-default HAPI_API_URL (from env or settings) into child env so shell helpers hit the same remote hub. It does not mirror CLI_API_TOKEN into wrapped agents (settings/prompt-backed secrets stay out of agent env; a fresh hapi re-reads ~/.hapi/settings.json, and systemd/env tokens already inherit). Prefer MCP list_peers inside a session. Web terminal PTYs still strip hub secrets. If --list fails with an auth/URL error, the message points at hapi auth login and the configured hub URL.

Disabling peer tools on a runner

Set HAPI_DISABLE_PEER_TOOLS=1 (also true/yes) in the runner environment to stop wrapped agents from browsing, messaging, or spawning other HAPI sessions — for example when one agent digging through the session list and pinging peers pollutes other sessions' contexts. The switch is not advertised-then-refused: the list_peers / inspect_peer / ping_peer / spawn_peer MCP tools are not registered on the session MCP server and not passed to --allowedTools / --tools, the peer steer block is dropped from agent system prompts (a pasted /sessions/<id> citation only reminds the agent it is a hub path, not a local file), and the peer core refuses with an explicit disabled error as defense in depth — so hapi ping-peer / hapi inspect-peer / hapi spawn-peer from inside a wrapped agent shell fails loudly too. Scope the env to the runner (systemd unit, launchd plist, or runner guard script); operators who leave it unset in their interactive terminal keep full hapi ping-peer CLI access.

Additional runner commands:

hapi runner list                      # List active sessions
hapi runner stop-session <sessionId>  # Stop a single session managed by the runner

Use --workspace-root <path> to restrict which directories the runner can browse and spawn sessions in. Repeat the flag to allow multiple directories; supports ~ expansion:

hapi runner start --workspace-root ~/projects --workspace-root ~/work

Without --workspace-root, directory browsing and spawning both accept paths anywhere the runner's OS account can access. The iOS directory picker starts at the home directory and can navigate above it. Configuring roots restricts both browsing and spawning to those roots, including symlink targets.

For running the hub and runner as persistent background services (pm2, launchd, systemd), see Deployment. Supervised installs should set HAPI_RUNNER_SUPERVISED=1 on the runner process (systemd Environment= / pm2 --env) so the web Restart control can safely stop-runner knowing the supervisor will cold-start it.

Multi-machine hubs

You can run one hub and runners on many machines (each machine installs its own CLI). When you upgrade the hub, upgrade the HAPI CLI on every machine that parents sessions. After the CLI binary on disk changes, that machine’s runner normally self-restarts via version handoff (unless HAPI_DISABLE_VERSION_HANDOFF=1). Until a runner reports the capabilities the hub requires, the web UI shows a Runner out of date banner (minimizable / snoozeable) with the host name and upgrade steps. The banner’s per-host Restart is only an escape hatch when handoff is stuck or disabled — the hub never downloads or installs packages on remotes.

Security notes

• Keep tokens secret and rotate if needed
• Use HTTPS for public access
• Restrict CORS origins in production

Firewall example (ufw)

ufw allow from 192.168.1.0/24 to any port 3006