Environment Variables

Overview

HAPI CLI can be configured using environment variables. These variables control connection settings, storage locations, feature flags, and runtime behavior.

Required Variables

CLI_API_TOKEN

Shared secret for authenticating with the HAPI hub. Required for CLI-hub communication.

CLI_API_TOKEN

string

required

Authentication token matching the hub’s token.Priority:

Environment variable (highest)
~/.hapi/settings.json file
Interactive prompt (first run)

export CLI_API_TOKEN=hapi_abc123xyz789...

How to get the token:

Check hub startup logs (generated on first run)
Read ~/.hapi/settings.json on the hub server
Ask your hub administrator
Use hapi auth login to save it locally

Example:

export CLI_API_TOKEN=hapi_abc123xyz789def456ghi789jkl012
hapi

Connection Settings

HAPI_API_URL

Base URL of the HAPI hub server.

HAPI_API_URL

string

default:"http://localhost:3006"

Hub server URL for API and Socket.IO connections.

export HAPI_API_URL=https://your-hub.com

Examples:

# Local hub
export HAPI_API_URL=http://localhost:3006

# Remote hub
export HAPI_API_URL=https://hapi.example.com

# Custom port
export HAPI_API_URL=http://192.168.1.100:8080

Verify connection:

hapi auth status

Storage and Paths

HAPI_HOME

Custom directory for HAPI data, settings, and logs.

HAPI_HOME

string

default:"~/.hapi"

Configuration and data directory. Supports ~ expansion.

export HAPI_HOME=~/custom/hapi/data

What’s stored in HAPI_HOME:

$HAPI_HOME/
├── settings.json           # User settings and token
├── access.key              # Encryption keys (if used)
├── runner.state.json       # Runner state
├── runner.state.json.lock  # Runner lock file
└── logs/
    ├── runner-*.log        # Runner logs
    └── session-*.log       # Session logs

Use cases: Multiple namespaces:

# Namespace 1
export HAPI_HOME=~/.hapi-prod
export CLI_API_TOKEN=prod-token
hapi

# Namespace 2
export HAPI_HOME=~/.hapi-dev
export CLI_API_TOKEN=dev-token
hapi

Custom location:

export HAPI_HOME=/mnt/data/hapi
hapi

Feature Flags

HAPI_EXPERIMENTAL

Enable experimental features (currently unused, reserved for future features).

HAPI_EXPERIMENTAL

boolean

default:"false"

Enable experimental features.Accepted values: true, 1, yes (case-insensitive)

export HAPI_EXPERIMENTAL=true

Examples:

# Enable
export HAPI_EXPERIMENTAL=true
# or
export HAPI_EXPERIMENTAL=1
# or
export HAPI_EXPERIMENTAL=yes

# Disable (default)
unset HAPI_EXPERIMENTAL
# or
export HAPI_EXPERIMENTAL=false

Agent Configuration

HAPI_CLAUDE_PATH

Custom path to the Claude CLI executable.

HAPI_CLAUDE_PATH

string

default:"claude (from PATH)"

Absolute path to a specific claude binary.

export HAPI_CLAUDE_PATH=/usr/local/bin/claude-beta

Use cases: Multiple Claude versions:

export HAPI_CLAUDE_PATH=/opt/claude-beta/bin/claude
hapi

Development builds:

export HAPI_CLAUDE_PATH=~/dev/claude/target/debug/claude
hapi

HAPI_HTTP_MCP_URL

Default MCP (Model Context Protocol) target URL for hapi mcp.

HAPI_HTTP_MCP_URL

string

HTTP URL for MCP stdio bridge target.

export HAPI_HTTP_MCP_URL=http://localhost:8080/mcp

Example:

export HAPI_HTTP_MCP_URL=http://localhost:8080/mcp
hapi mcp

Runner Configuration

HAPI_RUNNER_HEARTBEAT_INTERVAL

Interval (in milliseconds) between runner heartbeats.

HAPI_RUNNER_HEARTBEAT_INTERVAL

number

default:"60000"

Heartbeat interval in milliseconds (60000 = 60 seconds).

export HAPI_RUNNER_HEARTBEAT_INTERVAL=30000  # 30 seconds

Recommended values:

Default: 60000 (1 minute) - good balance
Frequent: 30000 (30 seconds) - faster failure detection
Infrequent: 120000 (2 minutes) - lower overhead

Example:

export HAPI_RUNNER_HEARTBEAT_INTERVAL=30000
hapi runner start

HAPI_RUNNER_HTTP_TIMEOUT

HTTP timeout (in milliseconds) for runner control requests.

HAPI_RUNNER_HTTP_TIMEOUT

number

default:"10000"

Timeout for HTTP requests to runner control API (10000 = 10 seconds).

export HAPI_RUNNER_HTTP_TIMEOUT=15000  # 15 seconds

Use cases: Slow networks:

export HAPI_RUNNER_HTTP_TIMEOUT=20000  # 20 seconds

Fast local networks:

export HAPI_RUNNER_HTTP_TIMEOUT=5000  # 5 seconds

Worktree Variables

These variables are set automatically by the runner when spawning sessions in worktrees. Do not set them manually.

When the runner spawns a session in a Git worktree, it sets these variables for the session process:

HAPI_WORKTREE_BASE_PATH

string

Absolute path to the base repository.Example: /home/user/projects/myproject

HAPI_WORKTREE_BRANCH

string

Git branch name for the worktree.Example: feature/new-ui

HAPI_WORKTREE_NAME

string

Worktree name (typically same as branch).Example: feature-new-ui

HAPI_WORKTREE_PATH

string

Absolute path to the worktree directory.Example: /home/user/projects/myproject/.worktrees/feature-new-ui

HAPI_WORKTREE_CREATED_AT

number

Unix timestamp (milliseconds) when worktree was created.Example: 1709712000000

Hub Server Variables

These variables configure the hub server when running hapi hub:

WEBAPP_HOST

string

default:"127.0.0.1"

Host interface for hub to bind to.

export WEBAPP_HOST=0.0.0.0  # All interfaces
hapi hub

Options:

127.0.0.1 - Localhost only (default, most secure)
0.0.0.0 - All interfaces (network access)
192.168.1.100 - Specific interface

Example:

export WEBAPP_HOST=0.0.0.0
hapi hub

WEBAPP_PORT

string

default:"3006"

HTTP port for hub server.

export WEBAPP_PORT=8080
hapi hub

Example:

export WEBAPP_PORT=8080
hapi hub

Debug Variables

DEBUG

Enable verbose debug logging.

DEBUG

string

Enable debug mode for detailed logging and error traces.

export DEBUG=1
hapi doctor

Examples:

# Enable debug mode
export DEBUG=1
hapi

# Run single command with debug
DEBUG=1 hapi doctor

Complete Configuration Example

A typical production setup:

# ~/.bashrc or ~/.zshrc

# Required: Authentication
export CLI_API_TOKEN=hapi_abc123xyz789def456ghi789jkl012

# Required: Hub URL
export HAPI_API_URL=https://hapi.example.com

# Optional: Custom data directory
export HAPI_HOME=~/.hapi

# Optional: Runner tuning
export HAPI_RUNNER_HEARTBEAT_INTERVAL=30000
export HAPI_RUNNER_HTTP_TIMEOUT=15000

# Optional: Custom Claude path
export HAPI_CLAUDE_PATH=/usr/local/bin/claude

# Optional: Experimental features
export HAPI_EXPERIMENTAL=false

Environment File

For development, create an .env file:

# .env
CLI_API_TOKEN=hapi_dev_token_123
HAPI_API_URL=http://localhost:3006
HAPI_HOME=~/.hapi-dev
HAPI_EXPERIMENTAL=true
DEBUG=1

Load with:

# Using dotenv
set -a
source .env
set +a
hapi

# Or export manually
export $(cat .env | xargs)
hapi

Per-Command Variables

Set variables for a single command:

# Use different hub for one session
HAPI_API_URL=https://other-hub.com hapi

# Use custom home for one session
HAPI_HOME=~/.hapi-test hapi codex

# Debug a single command
DEBUG=1 hapi doctor

Verification

Check current configuration:

# View all HAPI variables
env | grep HAPI

# View specific variables
echo $CLI_API_TOKEN
echo $HAPI_API_URL
echo $HAPI_HOME

# Check auth status
hapi auth status

Security Best Practices

Never commit environment files with secrets to version control.

1. Use `.env` files with `.gitignore`

# .gitignore
.env
.env.*
!.env.example

2. Create example files

# .env.example
CLI_API_TOKEN=your-token-here
HAPI_API_URL=http://localhost:3006
HAPI_HOME=~/.hapi

3. Use secrets managers in CI/CD

GitHub Actions:

env:
  CLI_API_TOKEN: ${{ secrets.HAPI_CLI_TOKEN }}
  HAPI_API_URL: ${{ secrets.HAPI_API_URL }}

GitLab CI:

variables:
  CLI_API_TOKEN: $HAPI_CLI_TOKEN  # Set in CI/CD settings
  HAPI_API_URL: $HAPI_API_URL

4. Rotate tokens regularly

# Generate new token
openssl rand -hex 32

# Update hub and all clients
export CLI_API_TOKEN=new-token
hapi auth login

Troubleshooting

Variable Not Taking Effect

Check if set:

env | grep HAPI

Re-export:

export HAPI_API_URL=https://new-hub.com
hapi auth status

Check shell config:

# Bash
source ~/.bashrc

# Zsh
source ~/.zshrc

Token Issues

Token not recognized:

# Verify token is set
echo "$CLI_API_TOKEN"

# Check priority
hapi auth status

# Re-login
hapi auth logout
hapi auth login

Custom Home Not Working

Check path expansion:

# This works
export HAPI_HOME=~/.hapi-custom

# This also works
export HAPI_HOME=/home/user/.hapi-custom

# Verify
echo $HAPI_HOME
ls -la $HAPI_HOME

Reference Table

Variable	Type	Default	Required	Description
`CLI_API_TOKEN`	string	-	Yes	Authentication token for hub
`HAPI_API_URL`	string	`http://localhost:3006`	No	Hub server URL
`HAPI_HOME`	string	`~/.hapi`	No	Data directory
`HAPI_EXPERIMENTAL`	boolean	`false`	No	Enable experimental features
`HAPI_CLAUDE_PATH`	string	`claude`	No	Custom Claude CLI path
`HAPI_HTTP_MCP_URL`	string	-	No	MCP bridge target URL
`HAPI_RUNNER_HEARTBEAT_INTERVAL`	number	`60000`	No	Heartbeat interval (ms)
`HAPI_RUNNER_HTTP_TIMEOUT`	number	`10000`	No	HTTP timeout (ms)
`WEBAPP_HOST`	string	`127.0.0.1`	No	Hub host interface
`WEBAPP_PORT`	string	`3006`	No	Hub HTTP port
`DEBUG`	string	-	No	Enable debug logging

Next Steps

Settings File - Understand the settings.json structure
Authentication - Configure CLI_API_TOKEN
Hub Command - Start the hub server

Commands

Configuration

​Overview

​Required Variables

​CLI_API_TOKEN

​Connection Settings

​HAPI_API_URL

​Storage and Paths

​HAPI_HOME

​Feature Flags

​HAPI_EXPERIMENTAL

​Agent Configuration

​HAPI_CLAUDE_PATH

​HAPI_HTTP_MCP_URL

​Runner Configuration

​HAPI_RUNNER_HEARTBEAT_INTERVAL

​HAPI_RUNNER_HTTP_TIMEOUT

​Worktree Variables

​HAPI_WORKTREE_BASE_PATH

​HAPI_WORKTREE_BRANCH

​HAPI_WORKTREE_NAME

​HAPI_WORKTREE_PATH

​HAPI_WORKTREE_CREATED_AT

​Hub Server Variables

​WEBAPP_HOST

​WEBAPP_PORT

​Debug Variables

​DEBUG

​Complete Configuration Example

​Environment File

​Per-Command Variables

​Verification

​Security Best Practices

​1. Use .env files with .gitignore

​2. Create example files

​3. Use secrets managers in CI/CD

​4. Rotate tokens regularly

​Troubleshooting

​Variable Not Taking Effect

​Token Issues

​Custom Home Not Working

​Reference Table

​Next Steps

Build docs developers (and LLMs) love

Overview

Required Variables

CLI_API_TOKEN

Connection Settings

HAPI_API_URL

Storage and Paths

HAPI_HOME

Feature Flags

HAPI_EXPERIMENTAL

Agent Configuration

HAPI_CLAUDE_PATH

HAPI_HTTP_MCP_URL

Runner Configuration

HAPI_RUNNER_HEARTBEAT_INTERVAL

HAPI_RUNNER_HTTP_TIMEOUT

Worktree Variables

HAPI_WORKTREE_BASE_PATH

HAPI_WORKTREE_BRANCH

HAPI_WORKTREE_NAME

HAPI_WORKTREE_PATH

HAPI_WORKTREE_CREATED_AT

Hub Server Variables

WEBAPP_HOST

WEBAPP_PORT

Debug Variables

DEBUG

Complete Configuration Example

Environment File

Per-Command Variables

Verification

Security Best Practices

1. Use `.env` files with `.gitignore`

2. Create example files

3. Use secrets managers in CI/CD

4. Rotate tokens regularly

Troubleshooting

Variable Not Taking Effect

Token Issues

Custom Home Not Working

Reference Table

Next Steps