Environment Variables

Happy CLI can be configured using environment variables to customize its behavior for different environments and use cases.

Core Configuration

HAPPY_SERVER_URL

URL of the Happy server to connect to.

HAPPY_SERVER_URL

string

default:"https://api.cluster-fluster.com"

The base URL for the Happy API server.

Example:

# Use local development server
export HAPPY_SERVER_URL=http://localhost:3005
happy

HAPPY_WEBAPP_URL

URL of the Happy web application.

HAPPY_WEBAPP_URL

string

default:"https://app.happy.engineering"

The URL for the Happy web application interface.

Example:

export HAPPY_WEBAPP_URL=http://localhost:3000

HAPPY_HOME_DIR

Custom location for Happy configuration and data files.

HAPPY_HOME_DIR

string

default:"~/.happy"

Directory path where Happy stores settings, keys, and logs. Supports ~ for home directory.

Example:

# Use separate directory for development
export HAPPY_HOME_DIR=~/.happy-dev
happy

When using HAPPY_VARIANT=dev, ensure HAPPY_HOME_DIR contains “dev” to avoid confusion.

Feature Flags

HAPPY_EXPERIMENTAL

Enable experimental features in Happy CLI.

HAPPY_EXPERIMENTAL

string

default:"false"

Accepts: true, 1, yes (case-insensitive)

Example:

export HAPPY_EXPERIMENTAL=true
happy

HAPPY_DISABLE_CAFFEINATE

Disable the caffeinate feature (macOS) that keeps the system awake during sessions.

HAPPY_DISABLE_CAFFEINATE

string

default:"false"

Accepts: true, 1, yes (case-insensitive)

Example:

export HAPPY_DISABLE_CAFFEINATE=true
happy

HAPPY_VARIANT

Specify the Happy variant (stable or dev).

HAPPY_VARIANT

string

default:"stable"

Accepts: stable or dev

Example:

export HAPPY_VARIANT=dev
export HAPPY_HOME_DIR=~/.happy-dev
happy

When using dev variant, Happy expects HAPPY_HOME_DIR to contain “dev” in the path and will show a warning if it doesn’t.

Daemon Configuration

HAPPY_DAEMON_HTTP_TIMEOUT

Timeout for daemon HTTP requests in milliseconds.

HAPPY_DAEMON_HTTP_TIMEOUT

number

default:"10000"

HTTP request timeout in milliseconds (10 seconds default).

Example:

export HAPPY_DAEMON_HTTP_TIMEOUT=30000
happy daemon start

HAPPY_DAEMON_HEARTBEAT_INTERVAL

Interval between daemon heartbeat checks in milliseconds.

HAPPY_DAEMON_HEARTBEAT_INTERVAL

number

default:"60000"

Heartbeat interval in milliseconds (60 seconds default).

Example:

export HAPPY_DAEMON_HEARTBEAT_INTERVAL=30000
happy daemon start

Claude Configuration

HAPPY_CLAUDE_PATH

Custom path to the Claude CLI executable.

HAPPY_CLAUDE_PATH

string

Absolute path to the claude binary. Useful for testing custom Claude builds.

Example:

export HAPPY_CLAUDE_PATH=/usr/local/bin/claude-dev
happy

HAPPY_USE_BUNDLED_CLAUDE

Force Happy to use its bundled Claude version.

HAPPY_USE_BUNDLED_CLAUDE

string

default:"0"

Set to 1 to use the Claude version bundled with Happy.

Example:

export HAPPY_USE_BUNDLED_CLAUDE=1
happy

CLAUDE_CONFIG_DIR

Custom location for Claude configuration files.

CLAUDE_CONFIG_DIR

string

default:"~/.claude"

Directory where Claude stores its configuration and project data.

Example:

export CLAUDE_CONFIG_DIR=~/.claude-dev
happy

CLAUDE_CODE_ENTRYPOINT

Specify the Claude Code entrypoint.

CLAUDE_CODE_ENTRYPOINT

string

default:"sdk-ts"

Entrypoint identifier for Claude Code SDK.

CLAUDE_SDK_MCP_SERVERS

Configure MCP servers for Claude SDK.

CLAUDE_SDK_MCP_SERVERS

string

MCP server configuration (automatically managed by Happy).

Codex Configuration

CODEX_HOME

Custom location for Codex configuration files.

CODEX_HOME

string

default:"~/.codex"

Directory where Codex stores its state and configuration.

Example:

export CODEX_HOME=~/.codex-dev
happy codex

HAPPY_HTTP_MCP_URL

Base URL for HTTP-based MCP bridge.

HAPPY_HTTP_MCP_URL

string

URL for the Happy MCP HTTP bridge.

Example:

export HAPPY_HTTP_MCP_URL=http://localhost:8080
happy codex

Gemini Configuration

GEMINI_API_KEY

API key for Gemini access.

GEMINI_API_KEY

string

Your Gemini API key for authentication.

Example:

export GEMINI_API_KEY=your-api-key-here
happy gemini

GEMINI_MODEL

Default Gemini model to use.

GEMINI_MODEL

string

default:"gemini-2.5-pro"

Model identifier. Available: gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite

Example:

export GEMINI_MODEL=gemini-2.5-flash
happy gemini

GOOGLE_CLOUD_PROJECT

Google Cloud Project ID for Workspace accounts.

GOOGLE_CLOUD_PROJECT

string

Required for Google Workspace accounts using Gemini.

Example:

export GOOGLE_CLOUD_PROJECT=my-project-id
happy gemini

AI Provider Configuration

These environment variables can be used to configure AI provider settings. They can also be set via AI Backend Profiles.

Anthropic

Variable	Description	Default
`ANTHROPIC_BASE_URL`	Custom API endpoint	`https://api.anthropic.com`
`ANTHROPIC_AUTH_TOKEN`	API authentication token	-
`ANTHROPIC_MODEL`	Default model to use	-

OpenAI

Variable	Description	Default
`OPENAI_API_KEY`	OpenAI API key	-
`OPENAI_BASE_URL`	Custom API endpoint	`https://api.openai.com`
`OPENAI_MODEL`	Default model to use	-

Azure OpenAI

Variable	Description	Default
`AZURE_OPENAI_API_KEY`	Azure OpenAI API key	-
`AZURE_OPENAI_ENDPOINT`	Azure endpoint URL	-
`AZURE_OPENAI_API_VERSION`	API version	-
`AZURE_OPENAI_DEPLOYMENT_NAME`	Deployment name	-

Together AI

Variable	Description	Default
`TOGETHER_API_KEY`	Together AI API key	-
`TOGETHER_MODEL`	Model to use	-

Tmux Configuration

Variable	Description	Default
`TMUX_SESSION_NAME`	Target tmux session name	Current/most recent
`TMUX_TMPDIR`	Tmux temporary directory	System default
`TMUX_UPDATE_ENVIRONMENT`	Update environment in tmux	-

Debug and Development

DEBUG

Enable debug logging and verbose output.

DEBUG

string

When set (any value), enables debug mode with verbose logging.

Example:

export DEBUG=1
happy

Debug mode produces verbose logs. Use only for troubleshooting.

HAPPY_PROJECT_ROOT

Project root directory (used in development).

HAPPY_PROJECT_ROOT

string

Root directory of the Happy project for development purposes.

HAPPY_RUN_SANDBOX_NETWORK_TESTS

Enable sandbox network integration tests.

HAPPY_RUN_SANDBOX_NETWORK_TESTS

string

default:"0"

Set to 1 to run network integration tests for sandboxing.

Using Environment Files

You can use .env files with Node’s --env-file flag:

# Create .env file
cat > .env << EOF
HAPPY_SERVER_URL=http://localhost:3005
HAPPY_HOME_DIR=~/.happy-dev
HAPPY_VARIANT=dev
DEBUG=1
EOF

# Run with environment file
node --env-file .env $(which happy)