# HAPI > HAPI is a local-first platform for running coding agents (Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, Kimi, GitHub Copilot, Antigravity, Pi, DeepSeek Harness) on your own machine and controlling them remotely from the web app/PWA, native iOS, Android and macOS apps, or Telegram. The `hapi` CLI (npm package `@twsxtd/hapi`) wraps the official agent CLIs; a self-hosted hub relays sessions to clients over REST + SSE, optionally through an end-to-end encrypted relay (WireGuard + TLS). Quick start: `npx @twsxtd/hapi hub --relay`, then `npx @twsxtd/hapi`. The CLI, hub and web app/PWA are free and open source under AGPL-3.0 (https://github.com/tiann/hapi); the native iOS, Android and macOS apps are paid. Website: https://hapi.run/ (English), https://hapi.run/zh/ (简体中文) ## Get Started - [Quick Start](https://hapi.run/docs/guide/quick-start.md): Install HAPI, start a hub with the built-in relay, and control your first coding agent session from your phone in a few minutes. - [Installation](https://hapi.run/docs/guide/installation.md): Install the HAPI CLI (Homebrew, npm, npx, binary or source), start the hub, choose a remote access option, and connect the web or native apps. - [Authentication](https://hapi.run/docs/guide/authentication.md): How CLIs, runners, the web app, native apps and Telegram sign in to a HAPI hub: the access token, QR sign-in, passkeys, JWT lifetimes and token rotation. - [Native apps (iOS / Android)](https://hapi.run/docs/guide/native-apps.md): Paid native HAPI apps for iOS, Android and macOS (Mac Catalyst): pairing with your hub, passkey sign-in, notifications and settings. - [Progressive Web App (PWA)](https://hapi.run/docs/guide/pwa.md): Install the free HAPI web app as a Progressive Web App on your phone or desktop, enable push notifications, and sign in with a passkey. ## Guide - [How it Works](https://hapi.run/docs/guide/how-it-works.md): HAPI architecture: the CLI wraps coding agents, a self-hosted hub syncs sessions, and web and native clients control them over REST, SSE and an encrypted relay. - [Session list](https://hapi.run/docs/guide/session-list.md): Find and organize HAPI sessions: presence badges, project grouping, search by details or message text, sort and filter, unread handling and row actions. - [Composer](https://hapi.run/docs/guide/composer.md): Send, queue, steer and schedule messages to your agent; pick model and effort; attach files; use slash commands, mentions and keyboard shortcuts. - [Fork, rewind, branch and export](https://hapi.run/docs/guide/conversation-history.md): Fork, rewind, branch across harnesses and export HAPI conversations, with per-agent support for Claude Code, Codex, OpenCode, Grok and Pi. - [Import local sessions](https://hapi.run/docs/guide/import-local-sessions.md): Import Claude Code, Codex, OpenCode and Pi conversations started outside HAPI and continue them from the web app. - [Peer sessions](https://hapi.run/docs/guide/peer-sessions.md): Let agents list, inspect, message and spawn other HAPI sessions with the peer tools, delivery modes (auto, queue, steer) and reply forwarding. - [Session-attached jobs](https://hapi.run/docs/guide/session-jobs.md): Attach long-running processes such as batch imports or overnight scripts to a HAPI session so the session list shows their progress after the agent goes idle. - [Usage and quotas](https://hapi.run/docs/guide/usage-and-quotas.md): Track agent working time with hapi usage, token usage per session, and Claude, Codex and Antigravity plan quotas and rate limits. - [Voice input and assistant](https://hapi.run/docs/guide/voice-assistant.md): Talk to your coding agent hands-free with the HAPI voice assistant, or dictate messages and review them before sending. - [Why HAPI?](https://hapi.run/docs/guide/why-hapi.md): How HAPI compares with Happy: a decentralized, self-hosted hub instead of a central cloud server, plus support for many coding agents. - [FAQ](https://hapi.run/docs/guide/faq.md): Answers to common questions about installing, securing, connecting and troubleshooting HAPI. ## Agents - [Supported Agents](https://hapi.run/docs/guide/agents.md): Coding agents supported by HAPI (Claude Code, Codex, Cursor, Grok Build, OpenCode, Kimi, Copilot, Antigravity, Pi, DeepSeek Harness) and which features each supports. - [Codex shared sessions](https://hapi.run/docs/guide/codex-shared-sessions.md): Share one Codex app-server between the official Codex terminal UI and HAPI web and native clients, including usage limits and attaching to desktop runtimes. ## Advanced - [CLI Reference](https://hapi.run/docs/guide/cli-reference.md): Every hapi command and its main flags: agent launchers, hub, runner, auth, resume, peer tools, jobs, usage and diagnostics. - [Configuration Reference](https://hapi.run/docs/guide/configuration.md): Every environment variable and settings.json key HAPI reads, grouped by hub, CLI, runner and agent, with defaults taken from the code. - [Namespace (Advanced)](https://hapi.run/docs/guide/namespace.md): Share one public HAPI hub across a small team by giving each member an isolated namespace through the access token suffix. - [Deployment](https://hapi.run/docs/guide/deployment.md): Run the HAPI hub and runner as persistent background services and expose the hub through the relay, a tunnel or a reverse proxy. - [Notifications](https://hapi.run/docs/guide/notifications.md): Get notified when HAPI sessions need input, request permission, fail or complete, via native push, Web Push, Telegram, ServerChan or voice. ## API - [Native companion API contract (phone + Wear + iOS)](https://hapi.run/docs/api/native-companion-contract.md): Contract for native companion apps (Android phone, Wear OS and iOS) that pair with a HAPI hub and receive push notifications. - [Native client contract](https://hapi.run/docs/api/client-contract/index.md): Overview of the client API contract that native HAPI clients (iOS, Android and others) implement against a hub. - [Auth & pairing](https://hapi.run/docs/api/client-contract/auth.md): How a native client obtains and refreshes credentials for a HAPI hub, including pairing, JWTs and passkeys. - [REST endpoints](https://hapi.run/docs/api/client-contract/rest.md): HAPI hub REST endpoints for native clients, grouped by feature. - [SSE stream (`GET /api/events`)](https://hapi.run/docs/api/client-contract/sse.md): The HAPI hub server-sent events stream (GET /api/events): connection, event types and reconnection. - [Message pagination, windowing, and optimistic sends](https://hapi.run/docs/api/client-contract/pagination.md): Message pagination, windowing and optimistic sends for native HAPI clients. - [Message decode tree](https://hapi.run/docs/api/client-contract/messages.md): How native HAPI clients decode session messages into chat blocks, mirroring the web chat pipeline. - [Session read state](https://hapi.run/docs/api/client-contract/read-state.md): How HAPI tracks and syncs per-session read state and unread counts across clients. - [Errors](https://hapi.run/docs/api/client-contract/errors.md): Error semantics, status codes and response shapes for HAPI hub /api endpoints. ## Optional - [Full documentation](https://hapi.run/llms-full.txt): every docs page above in a single Markdown file - [Privacy Policy](https://hapi.run/docs/privacy.md) - [Source code](https://github.com/tiann/hapi)