Hapi Remote Control

Remote control your AI coding sessions from anywhere — browser, phone, or tablet.

Official Website	https://hapi.run/
GitHub	https://github.com/tiann/hapi
Quick Start Docs	hapi.run/docs/guide/quick-start

Overview

Hapi is a local-first application that lets you run Claude Code / CodeX / Gemini sessions locally and control them remotely via Web, PWA, or Telegram Mini App. Monitor and manage your AI coding tasks from a phone or any browser.

Key Features

• Seamless Switching — Switch between local native and remote control modes
• Remote Sessions — Start remote sessions from any device
• Mobile Monitoring — Monitor and manage tasks from your phone or browser
• Permission Control — Remotely approve or reject tool permissions
• File Browsing — Browse project files and view git diffs
• Progress Tracking — Track task progress via to-do lists
• Multi-Backend Support — Works with Claude Code, CodeX, and Gemini CLI

Prerequisites

Node.js 18+ is required. If you need to install it, see Node.js Installation.

Installation

Visit the official quick-start guide for detailed installation instructions.

Launch the Hapi server with npx:

npx @twsxtd/hapi server

After startup, the terminal will display a Token credential and access URL.

Important

Save your Token credential — it's the only authentication key for connecting to and controlling Hapi.

Starting an AI Session

In your project directory, run the appropriate command:

# Start a Claude Code session
hapi claude

# Start a CodeX session
hapi codex

# Start a Gemini CLI session
hapi gemini

Once a session starts, the web interface will show the connection status.

LAN Access

At this point you can already access Hapi from your local network at http://<server-ip>:3006.

Remote Access with Cloudflare Tunnel

To access Hapi from outside your local network (including mobile), use Cloudflare Tunnel for secure remote access.

Prerequisites

• A domain name (any registrar)
• A Cloudflare account (free tier works)

Setup Steps

Follow the Cloudflare Tunnel documentation to configure:

1. Log in to the Cloudflare Zero Trust console
2. Create a new Tunnel
3. Install the cloudflared client on your server
4. Name your tunnel
5. Configure the public hostname
6. Set the service address to localhost:3006 (Hapi default port)
7. Complete the configuration

Install cloudflared

macOS

brew install cloudflare/cloudflare/cloudflared

Linux

curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

Windows

winget install Cloudflare.cloudflared

Quick Tunnel (Temporary)

For quick testing without a domain:

cloudflared tunnel --url http://localhost:3006

This generates a temporary public URL.

Named Tunnel (Persistent)

For permanent access with a custom domain:

# Login to Cloudflare
cloudflared tunnel login

# Create a tunnel
cloudflared tunnel create hapi

# Route DNS to the tunnel
cloudflared tunnel route dns hapi hapi.yourdomain.com

# Run the tunnel
cloudflared tunnel --config ~/.cloudflared/config.yml run hapi

Create ~/.cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: ~/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: hapi.yourdomain.com
    service: http://localhost:3006
  - service: http_status:404

Using Hapi

Once configured, you can access Hapi at:

1. Local: http://localhost:3006
2. LAN: http://<server-ip>:3006
3. Public: https://your-domain.com (if Cloudflare Tunnel is set up)

Usage steps:

1. Open the Hapi URL in your browser
2. Enter your Token to log in
3. Select the AI backend to launch (Claude / CodeX / Gemini)
4. Start controlling your AI sessions remotely

TIP

• Access from a mobile browser to monitor task progress on the go
• Install as a PWA for a native-app-like experience
• Multiple devices can connect and control simultaneously

Security Recommendations

• Protect your Token — Do not share it with anyone
• Use Cloudflare Access — If using public access, enable Cloudflare Access policies to restrict who can reach your tunnel
• Use HTTPS — Always use Cloudflare Tunnel for remote access; never expose port 3006 directly to the internet
• Rotate Tokens — Change your Token periodically

Troubleshooting

Cannot connect to the server

• Verify the Hapi server is running
• Check that port 3006 is not blocked by your firewall
• Confirm the Token is correct

Cloudflare Tunnel not working

• Verify your domain is added to Cloudflare
• Check that cloudflared is installed and running
• Review cloudflared logs for errors

More Help

See the Troubleshooting guide or visit Hapi GitHub Issues.