FAQ

General

What is HAPI?

HAPI is a local-first, self-hosted platform for running and controlling AI coding agents remotely (Claude Code, Codex, Cursor Agent, Grok Build, OpenCode, and more — see Supported Agents). It lets you start coding sessions on your computer and monitor/control them from your phone.

What does HAPI stand for?

HAPI (哈皮) is a Chinese transliteration of "Happy", reflecting the project's goal of making AI coding assistance a happier experience by freeing you from the terminal.

Is HAPI free?

Yes, HAPI is open source and free to use under the AGPL-3.0-only license.

What AI agents does HAPI support?

HAPI supports several coding agents, with Claude Code as the recommended option. See Supported Agents for the full list and per-agent setup notes.

Setup & Installation

Do I need a hub?

HAPI includes an embedded hub. Just run hapi hub on your machine - no external hub required.

hapi server remains supported as an alias.

How do I access HAPI from my phone?

Use the native iOS / Android apps or open the web app in your browser/PWA. Native apps pair with the hub's URL and access token; the guide covers building an app and scanning the companion QR.

For local network access:

http://<your-computer-ip>:3006

That cleartext URL is for a browser/PWA on your trusted LAN. Use HTTPS for native pairing: Android rejects HTTP, and iOS HTTP input remains subject to system network policy. Run hapi hub --relay or place an HTTPS reverse proxy/tunnel in front of the hub.

If your phone cannot connect, make sure the hub is not only listening on 127.0.0.1. For LAN access, set listenHost to 0.0.0.0 in ~/.hapi/settings.json or set HAPI_LISTEN_HOST=0.0.0.0, then restart hapi hub.

For internet access:

• Use the built-in relay tunnel: start the hub with hapi hub --relay to get a public URL via the tunwg relay (defaults to the official relay.hapi.run)
• If the hub has a public IP, access it directly (use HTTPS via reverse proxy for production)
• If behind NAT, set up your own tunnel (Cloudflare Tunnel, Tailscale, or ngrok)

What's the access token for?

The CLI_API_TOKEN is a shared secret that authenticates:

• CLI connections to the hub
• Web app logins
• Native app pairing and authentication
• Telegram account binding

It's auto-generated on first hub start and saved to ~/.hapi/settings.json.

Do you support multiple accounts?

Yes. We support lightweight multi-account access via namespaces for shared team hubs. See Namespace (Advanced).

Can I use HAPI without Telegram?

Yes. Telegram is optional. You can use a native iOS/Android app, open the web app in a browser, or install the PWA.

Usage

How do I approve permissions remotely?

1. When your AI agent requests permission (e.g., to edit a file), you'll see a notification
2. Open HAPI on your phone
3. Navigate to the active session
4. Approve or deny the pending permission

How do I receive notifications?

HAPI supports these notification channels:

1. PWA Push Notifications - Enable when prompted, works even when app is closed
2. Telegram Bot - See Telegram Setup
3. Native app notifications - Official Android and iOS apps use encrypted push delivery; pair your hub and allow notifications, with no push-provider setup required
4. ServerChan (Server酱) - Send notifications to WeChat and other channels; see ServerChan Setup

Can I start sessions remotely?

Yes, with runner mode:

1. Run hapi runner start on your computer
2. Open New Session in a native app or the web app
3. Select the online machine, directory and available agent, then create the session

How do I see what files were changed?

In the web session view, open Files. In native apps, open Session files from the chat menu to:

• Browse project files
• View git status
• See diffs of changed files

Can I send messages to the AI from my phone?

Yes. Open any session and use the chat interface to send messages directly to the AI agent.

Why did my session look idle when the agent woke itself?

Some agents (especially Cursor) can resume after idle from harness signals such as background Shell notify_on_output or /loop, without you sending a new HAPI message. HAPI updates the session's thinking indicator when the agent resumes work or requests permission, so the list reflects that activity.

Can I access a terminal remotely?

Yes. Open a session in the web app and tap the Terminal tab for a remote shell.

Linux and macOS hosts use Bun's POSIX PTY support. Windows hosts use Bun's ConPTY support, which requires Bun 1.3.14 or newer.

How do I use voice control?

The web voice assistant supports ElevenLabs, Gemini Live, and Qwen Realtime. Native apps support standard dictation: configure a transcription provider on the hub, record in the composer, then review and send the inserted text. See Voice input and assistant for setup details.

Security

Is my data safe?

HAPI keeps session history on the hub you operate, in ~/.hapi/ by default, rather than on a central HAPI account server. Your devices connect to that hub. Coding agents still use their configured model providers; optional voice, title generation, and notification features also contact external services. See the Privacy Policy for data handling and encrypted native push.

How secure is the token authentication?

The auto-generated token is 256-bit (cryptographically secure). For external access, always use HTTPS via a tunnel.

Can others access my HAPI instance?

Only if they have your access token. For additional security:

• Use a strong, unique token
• Always use HTTPS for external access
• Consider Tailscale for private networking

Troubleshooting

Why does a session stop when its laptop host sleeps?

Remote mode changes where you control the agent, not where it executes. The machine running the CLI or runner must remain awake. If the hub runs elsewhere, the web app may still load while that execution machine is unavailable. Running the hub on a server does not move an existing laptop session to that server.

First verify a small request with the laptop open. If that fails too, check the agent's pending permissions, CLI connection, and network before changing power settings. Terminal disconnection and operating-system sleep are separate problems: preserving a process after an SSH disconnect does not let it execute while its host is asleep.

For a MacBook that must work with the lid closed, use a supported external-display setup or a compatible closed-lid solution. Leaving the lid open with idle sleep managed is another option. Keep an active laptop powered and ventilated. After closing the lid, confirm new command output from the phone before relying on a long run.

This Apple Silicon MacBook setup guide includes a two-minute timestamp check and an optional Clamshell setup. Clamshell is a separate paid app with a trial; HAPI does not require it.

"Connection refused" error

• Ensure hub is running: hapi hub
• Check firewall allows port 3006
• Verify HAPI_API_URL is correct

My phone cannot access HAPI on the local network

If HAPI works on your computer but not from another device on the same LAN, check the hub bind address first. By default, HAPI listens on 127.0.0.1, which only accepts localhost connections.

Use one of these:

{
  "listenHost": "0.0.0.0"
}

export HAPI_LISTEN_HOST=0.0.0.0

Then restart hapi hub and open:

http://<your-computer-ip>:3006

This direct LAN URL is for browser/PWA access. The native Android companion requires HTTPS (hapi hub --relay, or your own HTTPS reverse proxy/tunnel).

Also verify your OS firewall allows inbound connections on port 3006.

"Invalid token" error

Run hapi doctor first - it shows whether CLI_API_TOKEN is set and where it comes from (environment variable or settings file).

• Re-run hapi auth login
• Check token matches in CLI and hub
• Verify ~/.hapi/settings.json has correct cliApiToken

Runner won't start

Run hapi doctor first - it shows runner status (including stale state), all hapi processes, and recent log files.

# Check status
hapi runner status

# List sessions the runner is aware of
hapi runner list

# Stop a specific runner-spawned session
hapi runner stop-session <session-id>

# Clear stale lock file
rm ~/.hapi/runner.state.json.lock

# Check logs
hapi runner logs

# Kill runaway hapi processes
hapi doctor clean

Claude Code not found

Install Claude Code or set custom path:

npm install -g @anthropic-ai/claude-code
# or
export HAPI_CLAUDE_PATH=/path/to/claude

Cursor Agent not found

Install Cursor Agent CLI:

# macOS/Linux
curl https://cursor.com/install -fsS | bash

# Windows (PowerShell)
irm 'https://cursor.com/install?win32=true' | iex

Ensure agent is on your PATH.

How do I run diagnostics?

hapi doctor

This is the first diagnostic step for most issues. It prints:

• CLI version, platform, and spawn diagnostics
• Configuration and relevant environment variables
• Contents of settings.json (token redacted)
• Whether CLI_API_TOKEN is set, and its source (it does not contact the hub or validate the token)
• Runner status and runner state (including stale state)
• All running hapi processes
• Recent log files (including runner logs)

To clean up runaway processes:

hapi doctor clean

Comparison

HAPI vs Happy

Aspect	Happy	HAPI
Design	Cloud-first	Local-first
Users	Multi-user	Single user by default; lightweight multi-account isolation via namespaces
Deployment	Multiple services	Single binary
Session history	Encrypted on server	Stored on your own hub

See Why HAPI for detailed comparison.

HAPI vs running Claude Code directly

Feature	Claude Code	HAPI + Claude Code
Remote access	No	Yes
Mobile control	No	Yes
Permission approval	Terminal only	Phone/web
Session persistence	No	Yes
Multi-machine	Manual	Built-in

Contributing

How can I contribute?

Visit our GitHub repository to:

• Report issues
• Submit pull requests
• Suggest features

Where do I report bugs?

Open an issue on GitHub Issues.