* feat(cli): MCP list_peers + runner hub auth inheritance Runner-spawned agents could not discover same-hub peers without sitting on the hub host or pasting a session id. Add MCP list_peers (in-process credentials), export HAPI_API_URL/CLI_API_TOKEN after auth init for shell fallbacks, and clearer auth failure hints. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): do not export default hub URL into HAPI_API_URL exportHapiHubAuthEnv was writing the implicit localhost default into process.env, which made maybeAutoStartServer skip starting the bundled hub. Only export HAPI_API_URL when the URL came from env or settings; always still export CLI_API_TOKEN. Also fill missing deliveryMode on abort restore so web typecheck matches RawSendError (main tip unblock). Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): widen initializeApiUrl mock return type in test Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): never export CLI_API_TOKEN; exclude self from list_peers Keep settings/prompt-backed hub secrets out of wrapped agent env so shell JWT+curl cannot bypass peer-tool approval. Fresh hapi re-reads settings; env-backed tokens already inherit. list_peers omits the calling session from the shortlist. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): resolve peer labels via summary/path like web titles list_peers was showing (unnamed) for ordinary sessions because titles live in metadata.summary.text. Match web getSessionTitle and collapse whitespace so each peer stays one agent-readable line. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli,hub): emit full peer ids and honor GET /sessions?limit Short 8-char prefixes collide across UUID namespaces; print full ids so resolveSessionByPrefix stays unambiguous. Honor optional limit after sort so listPeerSessions stops loading the whole namespace for scheduled counts. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(hub): type sessions limit test mock as Map<string, number> CI tsc rejected Map<string, null> for getNextScheduledAtBySessionIds. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli,hub): unbounded ping resolve; peer list order=updatedAt Keep GET /sessions?limit only for discovery callers. ping/inspect omit limit so full UUIDs outside the first 500 stay resolvable. Peer lists pass order=updatedAt so truncation matches newest-first. Basename fallback splits Windows paths. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): auto-approve ACP title List Peer Sessions Permission derivation prefers request.title; match the MCP tool title form so default-mode ACP sessions do not prompt on discovery. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): pad list_peers fetch; split hub URL vs token hints Fetch limit+2 when excluding the caller so overflow still surfaces at limit=100. Clarify that auth login only saves the token, not HAPI_API_URL. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(cli): use boolean overflow for ping-peer --list Match MCP list_peers: fetch limit+1 and mark hasMore instead of claiming an exact omitted count from a 200-row sample. Co-authored-by: Cursor <cursoragent@cursor.com> * fix(hub): tolerate mocked machineCache without expireInactive CI flake: 5s inactivity tick hit test doubles that only stubbed getOnlineMachinesByNamespace. Optional-call + stub the method. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
11 KiB
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, 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
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:
- Creates
~/.hapi/ - Generates a secure access token
- 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 |
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 |
- | - | ElevenLabs API key for voice |
ELEVENLABS_AGENT_ID |
Auto-created | - | Custom ElevenLabs agent ID |
OPENAI_API_KEY |
- | - | OpenAI API key for dictation (gpt-transcribe / gpt-live-transcribe) |
DEEPGRAM_API_KEY |
- | - | Deepgram API key for dictation (nova-3) |
GROQ_API_KEY |
- | - | Groq API key for dictation (whisper-large-v3) |
TRANSCRIPTION_BASE_URL |
- | - | OpenAI-compatible/local transcription base URL |
TRANSCRIPTION_MODEL |
- | - | Model for the OpenAI-compatible transcription endpoint |
TRANSCRIPTION_API_KEY |
- | - | Optional bearer token for that endpoint |
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
For running the hub and runner as persistent background services (pm2, launchd, systemd), see Deployment.
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