Configuration
All configuration lives in ~/penates/.env. setup.sh creates this file with sensible defaults; you only need to touch it for optional features or to change the port.
Environment variables
| Variable | Default | Description |
|---|---|---|
PORT | 3333 | TCP port the server listens on. |
AUTH_TOKEN | (required) | Required. Bearer token for all requests. Generated by setup.sh. Retrieve with grep AUTH_TOKEN ~/penates/.env. |
SESSION_PREFIX | cc- | Prefix added to all new session names in tmux. |
DEFAULT_PROJECT_DIR | ~ | Default working directory when creating a new session. |
TMUX_PATH | auto | Path to the tmux binary. Detected automatically via PATH scan; override only if tmux lives in an unusual location. |
TMUX_MOUSE | on | tmux mouse mode. Set to off if you use Moshi and want native touch selection in the terminal; scroll-wheel input is then unavailable in hub terminals. |
PROJECT_ROOTS | ~/Projects | Comma-separated directories scanned for project detection. |
BROWSE_ROOTS | $HOME | Colon-separated allow-list for the directory picker in the UI. ~ is accepted. Example: ~/Projects:/Volumes/SSD/code. |
PENATES_HOME | ~/.penates | Directory for persistent hub state (settings.json, known-sessions.json, board.json, audit.log). |
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY | auto | Web Push keys. Generated on first start; do not set these manually unless you are migrating from another installation. |
VAPID_SUBJECT | (required for Web Push) | Required for Apple Web Push. Must be a real HTTPS domain (not localhost). Example: https://penates.yourdomain.com. |
PREVIEW_DOMAIN | (none) | Base domain for the browser preview proxy. When set, preview.<PREVIEW_DOMAIN> reverse-proxies a local dev server. Leave empty to disable the feature. |
CF_ACCESS_TEAM_DOMAIN | (none) | Cloudflare Zero Trust team domain, e.g. yourteam.cloudflareaccess.com. Leave empty to disable CF Access JWT validation. |
CF_ACCESS_AUD | (none) | Cloudflare Access Application Audience tag (64-char hex string from the dashboard). Both CF_ACCESS_* variables must be set together to enable JWT validation. |
WHISPER_BIN | auto | Path to the whisper-cli binary for voice input. Detected automatically; override if installed in a non-standard location. |
WHISPER_MODEL | (required for voice) | Path to a .bin ggml whisper model file (for example ggml-large-v3-turbo-q5_0.bin). Required for voice input. |
VOICE_LANG | de | Default transcription language passed to whisper-cli. |
VOICE_ENABLED | true | Set to false to hide the microphone button entirely. Also disabled automatically when the binary or model is missing. |
Applying changes
The server reads .env at startup. After any change, restart the server:
launchctl kickstart -k gui/$(id -u)/com.penates