docs: add documentation site with VitePress setup

- 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)
2026-08-05 06:24:37 +00:00 · 2025-12-31 20:41:02 +08:00
parent 8f7dcf848b
commit 460c393006
15 changed files with 1452 additions and 402 deletions
@@ -0,0 +1,219 @@
+# Installation
+
+Install the HAPI CLI and set up the server.
+
+## Prerequisites
+
+- Claude Code, OpenAI Codex CLI, or Google Gemini CLI installed
+
+## Install the CLI
+
+```bash
+npm install -g @twsxtd/hapi
+```
+
+Or with Homebrew:
+
+```bash
+brew install tiann/tap/hapi
+```
+
+## Other install options
+
+<details>
+<summary>npx (no install)</summary>
+
+```bash
+npx @twsxtd/hapi
+```
+</details>
+
+<details>
+<summary>Prebuilt binary</summary>
+
+Download the latest release from [GitHub Releases](https://github.com/tiann/hapi/releases).
+
+```bash
+xattr -d com.apple.quarantine ./hapi
+chmod +x ./hapi
+sudo mv ./hapi /usr/local/bin/
+```
+</details>
+
+<details>
+<summary>Docker (server only)</summary>
+
+```bash
+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
+```
+</details>
+
+<details>
+<summary>Build from source</summary>
+
+```bash
+git clone https://github.com/tiann/hapi.git
+cd hapi
+bun install
+bun build:single-exe
+
+./cli/dist/hapi
+```
+</details>
+
+## Server setup
+
+Start the server:
+
+```bash
+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`
+
+<details>
+<summary>Config files</summary>
+
+```
+~/.hapi/
+├── settings.json      # Main configuration
+├── hapi.db           # SQLite database (server)
+├── daemon.state.json  # Daemon process state
+└── logs/             # Log files
+```
+</details>
+
+<details>
+<summary>Environment variables</summary>
+
+| 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 |
+</details>
+
+## CLI setup
+
+If the server is not on localhost, set these before running `hapi`:
+
+```bash
+export HAPI_SERVER_URL="http://your-server:3006"
+export CLI_API_TOKEN="your-token-here"
+```
+
+Or use interactive login:
+
+```bash
+hapi auth login
+```
+
+Authentication commands:
+
+```bash
+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/
+
+```bash
+export WEBAPP_URL="https://your-tunnel.trycloudflare.com"
+```
+
+Tailscale:
+
+https://tailscale.com/download
+
+```bash
+sudo tailscale up
+```
+
+Access via your Tailscale IP:
+
+```
+http://100.x.x.x:3006
+```
+
+ngrok:
+
+```bash
+ngrok http 3006
+```
+
+### Telegram setup
+
+Enable Telegram notifications and Mini App access:
+
+1. Message [@BotFather](https://t.me/BotFather) and create a bot
+2. Set the bot token and public URL
+3. Start the server and bind your account
+
+```bash
+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:
+
+```bash
+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
+
+<details>
+<summary>Firewall example (ufw)</summary>
+
+```bash
+ufw allow from 192.168.1.0/24 to any port 3006
+```
+</details>