hapi/docs/guide/installation.md

Installation

Install the HAPI CLI and set up the hub.

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 has three components:

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

How they work together

┌─────────────────────────────────────────────────────┐
│              Your Machine                           │
│                                                     │
│  ┌─────────┐    Socket.IO    ┌─────────────┐       │
│  │  CLI    │◄───────────────►│    Hub      │       │
│  │+ Agent  │                 │  + SQLite   │       │
│  └─────────┘                 └──────┬──────┘       │
│       ▲                             │ SSE          │
│       │ spawn                       ▼              │
│  ┌────┴────┐                 ┌─────────────┐       │
│  │ Runner  │◄────RPC────────►│   Web App   │       │
│  │(背景)   │                 └─────────────┘       │
│  └─────────┘                                       │
└─────────────────────────────────────────────────────┘
                    │
           [Tunnel / Public URL]
                    │
              ┌─────▼─────┐
              │ Phone/Web │
              └───────────┘

• CLI: Start a session with hapi. The CLI wraps your AI agent and syncs with the hub.
• Hub: Run hapi hub. Stores sessions, handles permissions, enables remote access.
• Runner: Run hapi runner start. Lets you spawn sessions from phone/web without keeping a terminal open.

Typical workflows

Local only: hapi hub → hapi → work in terminal

Remote access: hapi hub --relay → hapi runner start → control from phone/web

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

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

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_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
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 called only on demand; 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.

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

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.

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, manually entered spawn paths remain unrestricted. Session directory autocomplete and native pickers browse only beneath the runner's home directory; configuring roots makes both browsing and spawning use those roots instead.

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