FAQ

General

What is Hapimatic?

Hapimatic is a local-first platform for running and controlling AI coding agents (Claude Code, Codex, Gemini CLI, and OpenCode) remotely: you run it on your own machines, or use Hapimatic Cloud (in pilot). It lets you start coding sessions on your computer (or, on Hapimatic Cloud, your hosted VM) and monitor/control them from your phone.

Where does the name come from?

Hapimatic is based on hapi, a project whose name (哈皮) is a Chinese transliteration of "Happy": the goal was a happier AI coding experience, free of the terminal. Hapimatic is an independent project and is not affiliated with the authors of hapi or with hapi.dev.

Is Hapimatic free?

The self-hosted core is licensed under AGPL-3.0, and there is no charge to run it. Hapimatic Cloud, the hosted service, is a paid service and is in pilot.

What AI agents does Hapimatic support?

Four agent CLIs are supported at launch: Claude Code, Codex, Gemini CLI, and OpenCode. Gemini CLI and OpenCode sessions do not persist through a restart of the Hapimatic background service. Each one's sign-in and status is listed under Supported agent CLIs.

Setup & Installation

Do I need a server?

Hapimatic includes an embedded server. Just run hapi server on your machine - no external server required.

How do I access Hapimatic from my phone?

For local network access:

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

For internet access:

• If the server 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 server
• Web app logins
• Telegram account binding

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

Do you support multiple accounts?

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

Can I use Hapimatic 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 Hapimatic on your phone
3. Navigate to the active session
4. Approve or deny the pending permission

How do I receive notifications?

Hapimatic supports two methods:

1. PWA Push Notifications - Enable when prompted, works even when app is closed
2. Telegram Bot - See Telegram Setup

Can I start sessions remotely?

Yes, with daemon mode:

1. Run hapi daemon 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.

Security

Is my data safe?

When you self-host, Hapimatic is local-first:

• Its server and database run on a machine you or your team control (the database is stored in ~/.hapi/)
• There is no Hapimatic relay or sync service in between
• Your agents still send prompts and code to their model providers, as they do without Hapimatic
• If you reach it through a tunnel (Cloudflare Tunnel, ngrok) or turn on Telegram notifications, that provider carries the traffic. Cloudflare Tunnel and ngrok's HTTPS endpoints end TLS at the provider's edge, so the provider can read that traffic, including the access token you sign in with; Tailscale (including Funnel) ends TLS on your own machine

On Hapimatic Cloud, your sessions run on a VM that the operator can access. See Consent & Data Handling.

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 Hapimatic instance?

Only if they have your access token, or a Telegram account that was bound with it. A bound Telegram account keeps signing in after you change the token. To cut off every bound account, turn off Telegram sign-in: remove TELEGRAM_BOT_TOKEN from the server's environment (and the telegramBotToken entry in ~/.hapi/settings.json, if an older version saved it there), then restart the server. This also turns off Telegram notifications. Turning Telegram sign-in back on restores every account that was bound before, because the bindings stay in the server's database. There is no command yet to unbind a single account.

For additional security:

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

Troubleshooting

"Connection refused" error

• Ensure server is running: hapi server
• Check firewall allows port 3006
• Verify HAPI_SERVER_URL is correct

"Invalid token" error

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

Daemon won't start

# Check status
hapi daemon status

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

# Check logs
hapi daemon logs

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

How do I run diagnostics?

hapi doctor

This checks server connectivity, token validity, agent availability, and more.

Comparison

Hapimatic vs Happy

Aspect	Happy	Hapimatic
Design	Cloud-first	Local-first
Users	Multi-user	Single user
Deployment	Multiple services	Single binary
Data	Encrypted on server	Stored on a server you run (self-hosted)

See Why Hapimatic for detailed comparison.

Hapimatic vs running Claude Code directly

Feature	Claude Code	Hapimatic + 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

Support

How do I get help or report a problem?

For Hapimatic Cloud, contact your operator — the person who provisioned your instance. You can reach Hapimatic at hapimatic.com.