Skip to main content
This guide will get you from zero to a working HAPI session with remote access in under 2 minutes.

​
Prerequisites

You need at least one AI agent CLI installed: 
claude --version
Don’t have an AI agent CLI? Install Claude Code with:
npm install -g @anthropic-ai/claude-code

​
Installation

1

Install HAPI

Choose your preferred installation method:
npm install -g @twsxtd/hapi --registry=https://registry.npmjs.org
Tip: Use the official npm registry for global install. Some mirrors may not sync platform packages in time.
2

Start the Hub

Run the hub with the public relay for instant remote access:
hapi hub --relay
You’ll see output like this:
┌─────────────────────────────────────────────────────────┐
│                                                         │
│   HAPI Hub Started                                      │
│                                                         │
│   Local:   http://localhost:3006                        │
│   Remote:  https://abc123.relay.hapi.run                │
│                                                         │
│   Access Token: hapi_1a2b3c4d5e6f...                    │
│                                                         │
│   [QR CODE DISPLAYED HERE]                              │
│                                                         │
└─────────────────────────────────────────────────────────┘
Save your access token! It’s automatically saved to ~/.hapi/settings.json, but you’ll need it to log in from your phone.
The --relay flag enables end-to-end encrypted remote access via WireGuard + TLS. Your data is encrypted from your device to your machine—the relay only forwards packets it cannot read.
3

Start a Session

Open a new terminal and start your first coding session:
hapi
This starts a Claude Code session wrapped with HAPI. You’ll see the familiar Claude Code interface:
┌─────────────────────────────────────────────────────────┐
│  Claude Code (powered by HAPI)                          │
│                                                         │
│  Session registered: session_abc123                    │
│  Project: /Users/you/projects/myapp                     │
│                                                         │
│  You: _                                                 │
└─────────────────────────────────────────────────────────┘
Your session is now active and visible in the web UI.
4

Access from Your Phone

Three ways to access:Option 1: Scan QR CodeUse your phone’s camera to scan the QR code displayed in the hub terminal.Option 2: Open URLVisit the remote URL shown in the hub output (e.g., https://abc123.relay.hapi.run).Option 3: Copy to PhoneSend the URL to yourself via text/email/Slack and open it.
Login: Enter the access token when prompted. It’s saved in ~/.hapi/settings.json if you need to retrieve it:
cat ~/.hapi/settings.json | grep cliApiToken
5

Control Remotely

Once logged in, you’ll see your active session. Try these features:Send a MessageType a message to your AI agent directly from your phone:
"Create a new React component called Button"
Approve PermissionsWhen the AI requests file access, you’ll get a notification. Tap to approve or deny.View FilesTap the “Files” tab to browse your project, view git status, and see diffs.Switch Modes
  • Local → Remote: Send a message from your phone
  • Remote → Local: Press space twice in your terminal

​
What You Just Built

Congratulations! You now have:

Local AI Agent

Claude Code running in your terminal with full functionality

Remote Control

Web/PWA access from any device via encrypted relay

Session Persistence

All messages and state saved in SQLite (~/.hapi/hapi.db)

Real-Time Sync

Instant updates between terminal and phone via Socket.IO + SSE

​
Try Different Agents

HAPI supports multiple AI agents. Try switching: 
hapi
Each agent has the same remote control capabilities.

​
Common First-Time Tasks

​
Enable Notifications

When prompted in the web app, click “Allow” to enable push notifications. You’ll get notified when:
  • AI requests permissions
  • Sessions complete
  • Errors occur

​
Install as PWA

On mobile:
  1. Tap the share button in your browser
  2. Select “Add to Home Screen”
  3. HAPI appears as a native app icon
On desktop (Chrome/Edge):
  1. Click the install icon in the address bar
  2. Click “Install”

​
Check Status

Run diagnostics to verify everything is working: 
hapi doctor
Output: 
✓ Hub connectivity: OK
✓ Authentication: Valid token
✓ Claude CLI: Found at /usr/local/bin/claude
✓ Runner: Not running
✓ Sessions: 1 active

​
Troubleshooting

Connection refused?Make sure the hub is running in a separate terminal:
hapi hub --relay
Invalid token?Retrieve your token:
cat ~/.hapi/settings.json | grep cliApiToken
Or regenerate it:
rm ~/.hapi/settings.json
hapi hub --relay  # Creates new token
Relay connection issues?If UDP is blocked on your network, force TCP mode:
HAPI_RELAY_FORCE_TCP=true hapi hub --relay

​
Next Steps

Now that you have HAPI running, explore more features:

Installation Guide

Complete setup with Telegram, voice assistant, and background services

How It Works

Understand the architecture and data flow

Self-Hosting

Use Cloudflare Tunnel or Tailscale instead of the public relay

Runner Setup

Enable remote session spawning from your phone

​
Quick Reference

​
Essential Commands

# Hub management
hapi hub --relay          # Start hub with public relay
hapi hub                  # Start hub (local only)
hapi server               # Alias for 'hapi hub'

# Session commands
hapi                      # Start Claude Code
hapi codex                # Start Codex
hapi cursor               # Start Cursor Agent
hapi gemini               # Start Gemini
hapi opencode             # Start OpenCode

# Authentication
hapi auth status          # Show auth config
hapi auth login           # Save access token
hapi auth logout          # Clear credentials

# Diagnostics
hapi doctor               # Full system check
hapi doctor clean         # Kill runaway processes

# Runner (for remote spawning)
hapi runner start         # Start background runner
hapi runner stop          # Stop runner
hapi runner status        # Show runner info
hapi runner logs          # View runner logs

​
Configuration Files

~/.hapi/
├── settings.json         # Main configuration (token, URLs)
├── hapi.db              # SQLite database (sessions, messages)
├── runner.state.json    # Runner process state
└── logs/                # Log files

​
Environment Variables

export CLI_API_TOKEN="your-token"          # Authentication token
export HAPI_API_URL="http://localhost:3006"  # Hub URL
export HAPI_HOME="~/.hapi"                   # Config directory
For a complete list, see the Installation Guide.

Build docs developers (and LLMs) love

Get started for freeTalk to us