mirror of
https://github.com/wu736139669/hapi.git
synced 2026-08-05 06:24:37 +00:00
244 lines
6.2 KiB
Markdown
244 lines
6.2 KiB
Markdown
# FAQ
|
|
|
|
## General
|
|
|
|
### What is HAPI?
|
|
|
|
HAPI is a local-first, self-hosted platform for running and controlling AI coding agents (Claude Code, Codex, Gemini, OpenCode) remotely. 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?
|
|
|
|
- **Claude Code** (recommended)
|
|
- **OpenAI Codex**
|
|
- **Cursor Agent**
|
|
- **Google Gemini**
|
|
- **OpenCode**
|
|
|
|
## 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?
|
|
|
|
For local network access:
|
|
```
|
|
http://<your-computer-ip>:3006
|
|
```
|
|
|
|
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:
|
|
- If the hub has a public IP, access it directly (use HTTPS via reverse proxy for production)
|
|
- If behind NAT, set up a 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
|
|
- 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)](./namespace.md).
|
|
|
|
### Can I use HAPI without Telegram?
|
|
|
|
Yes. Telegram is optional. You can use the web app directly in any browser or install it as a 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 two methods:
|
|
|
|
1. **PWA Push Notifications** - Enable when prompted, works even when app is closed
|
|
2. **Telegram Bot** - See [Telegram Setup](./installation.md#telegram-setup)
|
|
|
|
### Can I start sessions remotely?
|
|
|
|
Yes, with runner mode:
|
|
|
|
1. Run `hapi runner start` on your computer
|
|
2. Your machine appears in the "Machines" list in the web app
|
|
3. Tap to spawn new sessions from anywhere
|
|
|
|
### How do I see what files were changed?
|
|
|
|
In the session view, tap the "Files" tab 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.
|
|
|
|
### Can I access a terminal remotely?
|
|
|
|
Yes, on Linux and macOS hosts. Open a session in the web app and tap the Terminal tab for a remote shell.
|
|
|
|
Windows hosts do not support the remote Terminal yet because the Bun PTY API used by HAPI is currently POSIX-only.
|
|
|
|
### How do I use voice control?
|
|
|
|
Set `ELEVENLABS_API_KEY`, open a session in the web app, and click the microphone button. See [Voice Assistant](./voice-assistant.md).
|
|
|
|
## Security
|
|
|
|
### Is my data safe?
|
|
|
|
Yes. HAPI is local-first:
|
|
- All data stays on your machine
|
|
- Nothing is uploaded to external servers
|
|
- The database is stored locally in `~/.hapi/`
|
|
|
|
### 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
|
|
|
|
### "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:
|
|
|
|
```json
|
|
{
|
|
"listenHost": "0.0.0.0"
|
|
}
|
|
```
|
|
|
|
```bash
|
|
export HAPI_LISTEN_HOST=0.0.0.0
|
|
```
|
|
|
|
Then restart `hapi hub` and open:
|
|
|
|
```bash
|
|
http://<your-computer-ip>:3006
|
|
```
|
|
|
|
Also verify your OS firewall allows inbound connections on port `3006`.
|
|
|
|
### "Invalid token" error
|
|
|
|
- Re-run `hapi auth login`
|
|
- Check token matches in CLI and hub
|
|
- Verify `~/.hapi/settings.json` has correct `cliApiToken`
|
|
|
|
### Runner won't start
|
|
|
|
```bash
|
|
# Check status
|
|
hapi runner status
|
|
|
|
# Clear stale lock file
|
|
rm ~/.hapi/runner.state.json.lock
|
|
|
|
# Check logs
|
|
hapi runner logs
|
|
```
|
|
|
|
### Claude Code not found
|
|
|
|
Install Claude Code or set custom path:
|
|
```bash
|
|
npm install -g @anthropic-ai/claude-code
|
|
# or
|
|
export HAPI_CLAUDE_PATH=/path/to/claude
|
|
```
|
|
|
|
### Cursor Agent not found
|
|
|
|
Install Cursor Agent CLI:
|
|
```bash
|
|
# 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?
|
|
|
|
```bash
|
|
hapi doctor
|
|
```
|
|
|
|
This checks hub connectivity, token validity, agent availability, and more.
|
|
|
|
## Comparison
|
|
|
|
### HAPI vs Happy
|
|
|
|
| Aspect | Happy | HAPI |
|
|
|--------|-------|------|
|
|
| Design | Cloud-first | Local-first |
|
|
| Users | Multi-user | Single user |
|
|
| Deployment | Multiple services | Single binary |
|
|
| Data | Encrypted on server | Never leaves your machine |
|
|
|
|
See [Why HAPI](./why-hapi.md) 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](https://github.com/tiann/hapi) to:
|
|
- Report issues
|
|
- Submit pull requests
|
|
- Suggest features
|
|
|
|
### Where do I report bugs?
|
|
|
|
Open an issue on [GitHub Issues](https://github.com/tiann/hapi/issues).
|