weishu
460c393006
- Initialize VitePress documentation site with config, index, and guides - Add guides for quick-start, installation, PWA, how-it-works, FAQ, and why HAPI - Update .gitignore to exclude VitePress cache directory - Update logo.svg with actual icon from web/public/icon.svg - Simplify README.md with link to full installation guide - Remove redundant WHY_NOT_HAPPY.md (content migrated to why-hapi guide)
3.9 KiB
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
Start the server:
hapi server
The server listens on http://localhost:3006 by default.
On first run, HAPI:
- Creates
~/.hapi/ - Generates a secure access token
- 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
Cloudflare Tunnel (recommended):
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:
- Message @BotFather and create a bot
- Set the bot token and public URL
- 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