Hapi Remote Control Setup Guide

Remote-control your AI coding assistants from anywhere.

Author: weishu Official docs: https://hapi.run/

Overview

Hapi is a local-first app that lets you run Claude Code, Codex, or Gemini sessions locally and control them remotely through Web, PWA, or Telegram Mini App. This means you can monitor and manage AI coding tasks from a phone or browser.

Links

Resource	URL
Hapi website	https://hapi.run/
Hapi repository	https://github.com/tiann/hapi
Quick start	Official quick-start docs
Cloudflare Tunnel docs	Create a remote tunnel

Core Features

Hapi provides these capabilities:

• Seamless switching between local native usage and remote control
• Remote sessions from any device
• Mobile monitoring through phone or browser
• Permission control to approve or reject tool permissions remotely
• File browsing and Git diff viewing
• Progress tracking through todo lists
• Multiple backends including Claude Code, Codex, and Gemini

Installation

Step 1: Install Hapi

Prerequisite

Make sure Node.js 18+ is installed. If needed, see Node.js installation.

Open the Hapi official quick-start docs for detailed installation methods.

Recommended quick start with npx:

npx @twsxtd/hapi server

After startup, it displays the token credential and access address.

Important

Save the token credential carefully. It is the only credential for connecting to and controlling the Hapi service.

Step 2: Start an AI Session

Run one of these commands in your project directory.

Start Claude Code:

hapi claude

Start Codex:

hapi codex

Start Gemini:

hapi gemini

After startup succeeds, the frontend shows the connection state.

LAN Access

At this point you can access and control your AI coding assistant on the local network through http://<server-ip>:3006.

Configure Cloudflare Tunnel

If you want to access Hapi from anywhere, including the public internet, use Cloudflare Tunnel for remote access.

Prerequisites

• A domain name
• A Cloudflare account. A free account is enough

Configuration Flow

Follow the Cloudflare Tunnel official docs:

1. Sign in to Cloudflare Zero Trust

2. Create a new tunnel

3. Install the cloudflared client

4. Configure the tunnel name

5. Configure public hostname

6. Set the service address

Set the service address to localhost:3006, Hapi's default port.

7. Finish configuration

Use Hapi

After configuration, you can access:

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

Usage steps:

1. Open the Hapi URL in a browser
2. Enter the token to sign in
3. Choose the AI backend to start, such as Claude, Codex, or Gemini
4. Start remote-controlling your AI coding assistant

Tips

• Access from a phone browser to monitor progress anywhere
• Install it as a PWA for an app-like experience
• Multiple devices can connect and control at the same time

Security Advice

• Do not leak the token
• If using public access, enable Cloudflare security features such as Access policies
• Rotate the token regularly
• Use only in trusted network environments

FAQ

Cannot connect to server

• Check whether the Hapi service is running
• Confirm the firewall is not blocking port 3006
• Check whether the token is correct

Cloudflare Tunnel configuration failed

• Confirm the domain has been added to Cloudflare correctly
• Check whether the cloudflared client is installed correctly
• View cloudflared logs for troubleshooting

More Questions

Read the FAQ or open Hapi GitHub Issues.

Advanced Optimization

To improve Hapi access speed, especially in mainland China networks, configure Cloudflare preferred IP routing:

Speed Optimization

With Cloudflare preferred IP configuration, latency can drop from hundreds of milliseconds to tens of milliseconds, closer to direct access.

See the detailed guide: Hapi Advanced: High-Speed Tunnel with Cloudflare Preferred IP