Copy .env.example to .env in the repo root and set values before starting the server. Variables marked (required) have no default and the server will not start correctly without them. See Configuration for a walkthrough of the most common options.
Core
| Variable | Default | Description |
|---|
PORT | 3333 | TCP port the HTTP server listens on. |
AUTH_TOKEN | (required) | Bearer token for all API and WebSocket requests. Generated by setup.sh. |
SESSION_PREFIX | cc- | Prefix prepended to every tmux session name created by the hub. |
DEFAULT_PROJECT_DIR | ~ | Default working directory for new sessions when none is specified. |
TMUX_PATH | (auto) | Absolute path to the tmux binary. Auto-detected via PATH when omitted. |
TMUX_MOUSE | on | Global tmux mouse mode. Set to off when using Moshi or mobile terminals where native touch selection matters. |
PROJECT_ROOTS | ~/Projects | Colon-separated list of root directories shown in the project picker. |
BROWSE_ROOTS | (none) | Additional roots allowed for /api/browse and new-project path selection. Colon-separated. Defaults to $HOME only. Example: ~/Projects:/Volumes/SSD/code. |
State directory
| Variable | Default | Description |
|---|
PENATES_HOME | ~/.penates | Directory for persistent hub state: settings.json, sessions.json, board.json, usage history, and models. Override in tests to isolate state. |
Browser preview
| Variable | Default | Description |
|---|
PREVIEW_DOMAIN | (none) | Base domain for the dev-server reverse proxy. Leave empty to disable the feature. Example: hub.example.com makes the proxy available at https://preview.hub.example.com/. Requires a single DNS CNAME record named preview pointing at your Cloudflare Tunnel; no wildcard DNS record is needed. Also requires a matching Cloudflare Access policy. |
Web Push
| Variable | Default | Description |
|---|
VAPID_PUBLIC_KEY | (auto) | VAPID public key for Web Push notifications. Generated automatically on first server start if empty. |
VAPID_PRIVATE_KEY | (auto) | VAPID private key. Generated automatically on first server start alongside the public key. |
VAPID_SUBJECT | https://your-domain.tld | VAPID subject URI. Apple Web Push requires a real HTTPS domain, not localhost. |
Cloudflare Access
Both variables must be set to enable JWT validation. Leaving either empty disables Cloudflare Access checking and the server accepts bearer tokens only.
| Variable | Default | Description |
|---|
CF_ACCESS_TEAM_DOMAIN | (none) | Your Cloudflare Zero Trust team domain, without https://. Found in the Cloudflare dashboard under Access. |
CF_ACCESS_AUD | (none) | Audience tag of your Cloudflare Access application. Found under Access > Applications > your app. |
Voice input is automatically disabled when WHISPER_BIN or WHISPER_MODEL are missing. Use VOICE_ENABLED=false to force-disable it even when both are present.
| Variable | Default | Description |
|---|
VOICE_ENABLED | (derived) | Set to false to hard-disable voice input. When omitted, the feature is enabled only if both WHISPER_BIN and WHISPER_MODEL resolve to existing files. |
WHISPER_BIN | /opt/homebrew/bin/whisper-cli | Absolute path to the whisper-cli binary. Override with WHISPER_BIN if installed elsewhere. |
WHISPER_MODEL | (none) | Absolute path to the .bin model file for whisper.cpp. setup.sh downloads ggml-large-v3-turbo-q5_0.bin into ~/.penates/models/. |
VOICE_LANG | de | Default transcription language passed to whisper.cpp. Use any language code supported by Whisper (e.g. en, de, fr). |
