.env.example

# PortOS Environment Variables
# Copy to .env and customize for your deployment.

# Database mode: "docker" (containerized pg, port 5561) or "native" (system pg, port 5432).
# PostgreSQL is REQUIRED — run `npm run setup:db` to provision it. ("file" = JSON storage
# is a development/test-only escape hatch, unsupported for production/federation; see docs/STORAGE.md.)
# PGMODE=docker

# PostgreSQL password (must match docker-compose.yml POSTGRES_PASSWORD in Docker mode)
# Note: Changing this after initial setup requires manually updating the PostgreSQL user password (or recreating the DB volume).
PGPASSWORD=portos

# Optional overrides (defaults auto-detect from PGMODE)
# PGHOST=localhost
# PGPORT=5432
# PGDATABASE=portos
# PGUSER=portos

# CDP browser automation host
# CDP_HOST=127.0.0.1

# Server host binding (hostname used for self-links and federation peer discovery)
# PORTOS_HOST=my-machine.ts.net

# Loopback HTTP port spawned when HTTPS is active so local curl skips the cert (default: 5553)
# PORTOS_HTTP_PORT=5553

# pm2 restarts portos-server when its RSS crosses this (memory-leak safety valve).
# Default 4G fits small installs; raise it on a big-RAM workstation so a long
# session / heavy SSE load doesn't cause spurious restarts (e.g. 32G on 128 GB).
# PORTOS_SERVER_MAX_MEMORY=32G

# Same ceiling for the Vite dev server (portos-ui). Default 1G — a dev server that
# transforms modules on demand should sit well under that; raise it only if a huge
# client tree makes Vite restart during normal editing.
# PORTOS_UI_MAX_MEMORY=2G

# Override the base URLs advertised to clients (auto-derived from PORTOS_HOST/PORT if unset)
# PORTOS_API_URL=https://my-machine.ts.net:5555
# PORTOS_UI_URL=https://my-machine.ts.net:5555

# Server host binding for Express listen (default: 0.0.0.0)
# HOST=0.0.0.0

# Public-facing hostname baked into OAuth redirect URIs for Google Calendar/Gmail
# (googleAuth.js) and Spotify (spotifyAuth.js). Google defaults to "localhost".
# Spotify prefers the origin the browser actually used to reach the request, and
# only falls back to this value (then the detected Tailscale hostname/HTTPS state,
# then localhost). Set this override when the provider must use another host.
# PUBLIC_HOST=host-example.ts.net

# Explicit override for the Spotify OAuth redirect URI (spotifyAuth.js). When set, it is
# used verbatim instead of the request origin, PUBLIC_HOST, or the detected Tailscale
# hostname/HTTPS state.
# It must match the redirect URI registered in the Spotify dashboard byte-for-byte.
# SPOTIFY_REDIRECT_URI=https://host-example.ts.net:5555/api/spotify/oauth/callback

# OpenClaw integration (configured via Settings UI; env overrides take precedence)
# OPENCLAW_ENABLED=true
# OPENCLAW_BASE_URL=https://your-openclaw-instance.example.com
# OPENCLAW_AUTH_TOKEN=your_token_here
# OPENCLAW_AUTH_HEADER=Authorization
# OPENCLAW_AUTH_SCHEME=Bearer
# OPENCLAW_LABEL=OpenClaw Runtime
# OPENCLAW_DEFAULT_SESSION=
# OPENCLAW_DEFAULT_AGENT_ID=main
# OPENCLAW_TIMEOUT_MS=30000

# Chief of Staff runner endpoint (used when CoS runs as a separate process)
# COS_RUNNER_URL=http://localhost:5558

# Active local LLM backend: "ollama" or "lmstudio" (chosen at setup time; managed in Settings → Local LLMs)
# LLM_BACKEND=ollama

# LM Studio local inference server URL
# LM_STUDIO_URL=http://localhost:1234

# LM Studio model used by the Moltworld explorer (default: gpt-oss-20b)
# LM_STUDIO_MODEL=gpt-oss-20b

# Enable LM Studio thoughts in the Moltworld explorer (default: true)
# LM_STUDIO_ENABLED=true

# Ollama local inference server URL (defaults to http://localhost:11434)
# OLLAMA_URL=http://localhost:11434

# Ollama-compatible host:port alias used when OLLAMA_URL is unset (default: localhost:11434)
# OLLAMA_HOST=localhost:11434

# Maximum simultaneous requests to each local LLM endpoint (default: 1)
# LOCAL_LLM_MAX_CONCURRENCY=1

# Maximum Codex image-generation runtime in milliseconds (default: 1200000 / 20 minutes)
# CODEX_TIMEOUT_MS=1200000

# Maximum Grok image-generation runtime in milliseconds (default: 1200000 / 20 minutes)
# GROK_TIMEOUT_MS=1200000

# Maximum Antigravity image-generation runtime in milliseconds (default: 1200000 / 20 minutes)
# AGY_IMAGEGEN_TIMEOUT_MS=1200000

# Path to the Claude CLI binary (defaults to system PATH)
# CLAUDE_PATH=/usr/local/bin/claude

# Codex CLI home directory scanned for token-usage stats in the AI provider usage
# dashboard (providerUsage.js). Defaults to ~/.codex. Set this if your Codex CLI
# stores its session logs somewhere other than the default location.
# CODEX_HOME=/path/to/.codex

# Path to a specific pg_dump binary for database backups. By default PortOS
# auto-selects one whose major version is >= the running server (it scans
# Homebrew kegs + Postgres.app). Set this if auto-discovery can't find a new
# enough pg_dump on your platform (e.g. Linux/Windows multi-version installs).
# PORTOS_PGDUMP=/opt/homebrew/opt/postgresql@17/bin/pg_dump

# Duration (minutes) for Moltworld agent sessions
# MOLTWORLD_DURATION_MINUTES=60

# Memory backend — "file" is dev/test only; leave unset for production (PostgreSQL required)
# MEMORY_BACKEND=file

# CoS log verbosity — set to "debug" to enable verbose Chief of Staff event logs
# COS_LOG_LEVEL=debug

# Hugging Face token for authenticated model downloads (three equivalent env var names accepted)
# HF_TOKEN=hf_...
# HUGGINGFACE_HUB_TOKEN=hf_...
# HUGGINGFACEHUB_API_TOKEN=hf_...
# Additional alias read by the Hugging Face catalog API client (huggingFaceCatalog.js)
# for authenticated model-metadata lookups; falls back to HF_TOKEN when unset.
# HUGGINGFACE_TOKEN=hf_...

# Google Gemini API key (used by the Google AI provider in Settings → AI Providers)
# GOOGLE_API_KEY=AIza...

# CivitAI API key for LoRA / model downloads from civitai.com
# CIVITAI_API_KEY=your_civitai_api_key_here

# Absolute path to the bash binary used to run PortOS's bundled *.sh scripts
# (e.g. scripts/db.sh). Auto-detected if unset; on Windows it prefers Git Bash,
# because a bare `bash` often resolves to WSL, which can't see drive paths.
# PORTOS_BASH=/bin/bash

# Shell binary for interactive PTY sessions (the Shell page, agent TUI shells).
# Auto-detected if unset: on Windows PowerShell 7, else Windows PowerShell, else
# cmd.exe (last, because it can't reach another drive by anything you'd type —
# see server/lib/interactiveShellResolver.js); on macOS/Linux $SHELL, else zsh.
# Windows: PORTOS_SHELL=C:\Program Files\Git\bin\bash.exe
# PORTOS_SHELL=/bin/fish

# Extra directory roots exposed in the workspace file browser, on top of the
# defaults (home, /tmp, /Users, /Volumes, /mnt, /media, /opt — on Windows: home,
# the temp dir, and any lettered non-system drive). Separated by the platform
# path delimiter: `:` on macOS/Linux, `;` on Windows, where a colon would split
# a value like D:\repos at the drive letter.
# PORTOS_WORKSPACE_ROOTS=/home/user/projects:/srv/git
# Windows: PORTOS_WORKSPACE_ROOTS=D:\repos;E:\projects

# PyTorch CUDA index URL suffix for Windows GPU installs (e.g. cu121); auto-detected on Linux
# PORTOS_TORCH_CUDA_INDEX=cu121

# Path to the media-models registry JSON file (defaults to data/media-models.json)
# PORTOS_MEDIA_MODELS_FILE=/path/to/custom/media-models.json

# LM Studio models directory override (default: ~/LM Studio/models)
# LM_STUDIO_MODELS_DIR=/path/to/lm-studio/models

# Ollama models directory override (default: ~/.ollama/models)
# OLLAMA_MODELS=/path/to/ollama/models

# Ollama context window size passed to new model loads (default: 32768)
# OLLAMA_NUM_CTX=32768

# Video process grace period after output completion in milliseconds (default: 40000)
# VIDEOGEN_COMPLETION_WATCHDOG_MS=40000

# Terminate an idle queued video job after this many milliseconds (default: 1800000 / 30 minutes)
# MEDIA_JOB_WATCHDOG_VIDEO_MS=1800000

# Terminate an idle queued image job after this many milliseconds (default: 300000 / 5 minutes)
# MEDIA_JOB_WATCHDOG_IMAGE_MS=300000

# Terminate an idle queued Codex job after this many milliseconds (default: 1200000 / 20 minutes)
# MEDIA_JOB_WATCHDOG_CODEX_MS=1200000

# Terminate an idle queued training job after this many milliseconds (default: 1800000 / 30 minutes)
# MEDIA_JOB_WATCHDOG_TRAINING_MS=1800000

# Terminate an idle queued audio job after this many milliseconds (default: 600000 / 10 minutes)
# MEDIA_JOB_WATCHDOG_AUDIO_MS=600000

# LoRA step-time multiplier used to detect a soft training stall (default: 6)
# LORA_TRAIN_STALL_STEP_MULTIPLIER=6

# Step intervals required before the adaptive LoRA stall budget arms (default: 3)
# LORA_TRAIN_STALL_MIN_SAMPLES=3

# Minimum adaptive LoRA stall budget in milliseconds (default: 90000)
# LORA_TRAIN_STALL_MIN_BUDGET_MS=90000

# Maximum adaptive LoRA stall budget in milliseconds (default: 900000 / 15 minutes)
# LORA_TRAIN_STALL_MAX_BUDGET_MS=900000

# LoRA warmup stall budget before step timing stabilizes (default: 1200000 / 20 minutes)
# LORA_TRAIN_STALL_WARMUP_BUDGET_MS=1200000

# Automatic LoRA checkpoint resumes allowed after soft stalls (default: 2; 0 disables)
# LORA_TRAIN_STALL_MAX_AUTO_RESUMES=2

# Ingredient catalog revisions retained per ingredient (default: 50)
# CATALOG_REVISION_RETENTION=50

# LM Studio model id auto-installed for voice tool calling (default: built-in fallback chain)
# PORTOS_VOICE_DEFAULT_TOOL_MODEL=lmstudio-community/Qwen2.5-3B-Instruct-GGUF

# Signal sync config file path (default: SIGNAL_DIR/config.json)
# SIGNAL_CONFIG_PATH=/path/to/signal/config.json

# Privacy Center PII Vault encryption key — 32 bytes, hex (64 chars) or base64.
# Auto-generated and appended to .env on the first vault write if unset. Back
# it up: losing it makes every encrypted vault value unrecoverable.
# PRIVACY_VAULT_KEY=<64 hex chars>