hapi/docs/guide/installation.md

Installation

Install the HAPI CLI and set up the server.

Prerequisites

• Claude Code, OpenAI Codex CLI, or Google Gemini CLI installed

Install the CLI

npm install -g @twsxtd/hapi

Or with Homebrew:

brew install tiann/tap/hapi

Other install options

npx (no install)

npx @twsxtd/hapi

Prebuilt binary

Download the latest release from GitHub Releases.

xattr -d com.apple.quarantine ./hapi
chmod +x ./hapi
sudo mv ./hapi /usr/local/bin/

Docker (server only)

docker pull ghcr.io/tiann/hapi-server:latest

docker run -d \
  --name hapi-server \
  -p 3006:3006 \
  -v ~/.hapi:/root/.hapi \
  -e CLI_API_TOKEN=your-secret-token \
  ghcr.io/tiann/hapi-server:latest

Build from source

git clone https://github.com/tiann/hapi.git
cd hapi
bun install
bun build:single-exe

./cli/dist/hapi

Server setup

The server can be deployed on:

• Local desktop (default) - Run on your development machine
• Remote server - Deploy on a VPS, cloud server, or any machine with network access

Start the server:

hapi server

The server listens on http://localhost:3006 by default.

On first run, HAPI:

1. Creates ~/.hapi/
2. Generates a secure access token
3. Prints the token and saves it to ~/.hapi/settings.json

Config files

~/.hapi/
├── settings.json      # Main configuration
├── hapi.db           # SQLite database (server)
├── daemon.state.json  # Daemon process state
└── logs/             # Log files

Environment variables

Variable	Default	Description
CLI_API_TOKEN	Auto-generated	Shared secret for authentication
HAPI_SERVER_URL	http://localhost:3006	Server URL for CLI
WEBAPP_PORT	3006	HTTP server port
HAPI_HOME	~/.hapi	Config directory path
DB_PATH	~/.hapi/hapi.db	Database file path
CORS_ORIGINS	-	Allowed CORS origins

CLI setup

If the server is not on localhost, set these before running hapi:

export HAPI_SERVER_URL="http://your-server:3006"
export CLI_API_TOKEN="your-token-here"

Or use interactive login:

hapi auth login

Authentication commands:

hapi auth status
hapi auth login
hapi auth logout

Each machine gets a unique ID stored in ~/.hapi/settings.json. This allows:

• Multiple machines to connect to one server
• Remote session spawning on specific machines
• Machine health monitoring

Operations

Remote access

If the server is deployed on a machine with a public IP, you can access it directly via http://your-server-ip:3006. Use HTTPS (via reverse proxy like Nginx or Caddy) for production.

If the server is behind NAT, use one of these options:

Cloudflare Tunnel (recommended for NAT)

https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/

export WEBAPP_URL="https://your-tunnel.trycloudflare.com"

Tailscale

https://tailscale.com/download

sudo tailscale up

Access via your Tailscale IP:

http://100.x.x.x:3006

ngrok

ngrok http 3006

Telegram setup

Enable Telegram notifications and Mini App access:

1. Message @BotFather and create a bot
2. Set the bot token and public URL
3. Start the server and bind your account

export TELEGRAM_BOT_TOKEN="your-bot-token"
export WEBAPP_URL="https://your-public-url"

hapi server

Then message your bot with /start, open the app, and enter your CLI_API_TOKEN.

Daemon setup

Run a background service for remote session spawning:

hapi daemon start
hapi daemon status
hapi daemon logs
hapi daemon stop

With the daemon running:

• Your machine appears in the "Machines" list
• You can spawn sessions remotely from the web app
• Sessions persist even when the terminal is closed

Security notes

• Keep tokens secret and rotate if needed
• Use HTTPS for public access
• Restrict CORS origins in production

Firewall example (ufw)

ufw allow from 192.168.1.0/24 to any port 3006