Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

18.1 KB
Raw Blame
# 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).
# Values are read literally (surrounding quotes stripped; no inline comments or $ expansion).
# `npm run setup:db` and scripts/db.sh pass the resolved values to Docker Compose, so the
# container is provisioned with exactly what PortOS connects with. If you run `docker compose`
# directly, Compose applies its OWN grammar to this file: a `#` after whitespace starts a
# comment and `$` expands. Wrap a value containing either in single quotes, e.g. PGPASSWORD='pa$$word'.
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

# Extra hostnames a browser may use to reach PortOS (comma-separated; a leading dot admits
# subdomains). IP literals, single-label names, .ts.net/.local/.lan/.internal/.home.arpa names,
# the machine hostname and PORTOS_HOST are always accepted; any other Host is refused with
# HOST_NOT_ALLOWED to block DNS rebinding.
# PORTOS_ALLOWED_HOSTS=portos.example.com,.home.example.net

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

# Port the Express server listens on (server/index.js; default: 5555 from lib/ports.js)
# PORT=5555

# VNC port the Remote Desktop broker connects to on this machine
# (remoteDesktop.js; default: 5900). A non-numeric or out-of-range value falls
# back to the default rather than failing.
# PORTOS_VNC_PORT=5900

# 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

# 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). PM2 honors this for
# portos-server only (exported HOST wins over .env); CoS/CDP stay on loopback.
# 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

# Eidoverse world server endpoints (eidoverseWorld.js). The WebSocket URL defaults
# to ws://127.0.0.1:<eidoverse port>/ws; the HTTP URL is derived from it unless set.
# Point these at another host only when the world runs off-box.
# EIDOVERSE_WS_URL=ws://127.0.0.1:8940/ws
# EIDOVERSE_HTTP_URL=http://127.0.0.1:8940/
# Optional dedicated 64-character lowercase hex broker credential, shared with the local
# managed-visitor host. Empty/unset disables this lane; never reuse an instance password
# or ordinary world join token. See docs/features/managed-visitors.md.
# PORTOS_EIDOVERSE_VISITOR_TOKEN=

# 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

# Optional CLI config paths used to recognize custom forge hosts for managed apps
# whose work tracker is set to Auto. Defaults follow gh/glab and XDG platform paths.
# GH_CONFIG_DIR=
# GLAB_CONFIG_DIR=
# XDG_CONFIG_HOME=
# XDG_CONFIG_DIRS=
# APPDATA=

# 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 Grok VIDEO runtime in milliseconds (videoGen/grok.js; default: 1800000 /
# 30 minutes). Video takes longer than an image, so this cap is separate from
# GROK_TIMEOUT_MS — keep it above the 20-minute cloud-lane idle watchdog.
# GROK_VIDEO_TIMEOUT_MS=1800000

# Maximum fal.ai queue video-generation runtime in milliseconds (videoGen/fal.js;
# default: 1200000 / 20 minutes) — a queue render can sit behind other tenants'
# jobs before it starts, so this bounds the whole submit→poll→download run.
# FAL_VIDEO_TIMEOUT_MS=1200000

# Maximum fal.ai image-generation runtime in milliseconds (imageGen/fal.js;
# default: 900000 / 15 minutes) — bounds the whole submit→poll→download run.
# FAL_IMAGE_TIMEOUT_MS=900000

# Maximum reactor.inc fast-h3 video-generation runtime in milliseconds
# (videoGen/reactor.js; default: 1200000 / 20 minutes) — same reasoning as
# FAL_VIDEO_TIMEOUT_MS above.
# REACTOR_VIDEO_TIMEOUT_MS=1200000

# Maximum Runway video-generation runtime in milliseconds (videoGen/runway.js;
# default: 1200000 / 20 minutes) — a task can wait THROTTLED behind the
# account's concurrency limit, so this bounds the whole submit→poll→download run.
# RUNWAY_VIDEO_TIMEOUT_MS=1200000

# Maximum wait for a Runway image task, including provider queue time (milliseconds).
# RUNWAY_IMAGE_TIMEOUT_MS=900000

# Optional Python executable in an environment with reactor-sdk installed.
# Defaults to data/venvs/reactor created by npm run setup:reactor.
# REACTOR_PYTHON_PATH=

# 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

# fal.ai API key for the fal.ai queue video backend (Video Gen page, FableLoom).
# Settings > Video Gen's stored key wins when both are set.
# FAL_KEY=your_fal_api_key_here

# reactor.inc API key for the reactor.inc fast-h3 video backend (Video Gen
# page, FableLoom). Settings > Video Gen's stored key wins when both are set.
# REACTOR_API_KEY=your_reactor_api_key_here

# Runway developer API key for the Runway video backend (Video Gen page, Music
# Video shots). Settings > Video Gen's stored key wins when both are set.
# RUNWAYML_API_SECRET=your_runway_api_key_here

# Artificial Analysis API key for synchronizing model quality, speed, and pricing comparison benchmarks
# ARTIFICIAL_ANALYSIS_API_KEY=your_artificial_analysis_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

# Python interpreter scripts/setup-image-video.sh uses as the venv base
# (setupScriptRunner.js). An explicit value always wins; on Windows PortOS
# otherwise auto-detects one, avoiding a conda base whose venv can't load torch.
# PYTHON_BIN=/usr/bin/python3

# 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

# Pinokio installation used by the explicit Models Status duplicate scan.
# PINOKIO_HOME takes precedence over PINOKIO_PATH; default: ~/pinokio.
# PINOKIO_HOME=/path/to/pinokio
# PINOKIO_PATH=/path/to/pinokio

# 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

# Slotstream model cache directory override (slotstreamModels.js; default:
# ~/.slotstream/models). The binary always lives in ~/.slotstream/bin.
# SLOTSTREAM_MODEL_DIR=/path/to/slotstream/models

# Abandon a Slotstream checkpoint download after this many milliseconds with no
# bytes received (slotstreamModelManager.js; default: 1200000 / 20 minutes). A
# transfer that is still receiving bytes is never cut off by this, and an
# abandoned one keeps its progress so a retry resumes rather than restarts.
# SLOTSTREAM_IDLE_STALL_MS=1200000

# Abort a speculative-decoding model download after this many milliseconds with
# no bytes received (specDecodeModels.js; default: 1200000 / 20 minutes). Raise
# it for a slow Hugging Face/CDN handshake; a download still receiving bytes is
# never cut off by this.
# SPEC_DECODE_IDLE_STALL_MS=1200000

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

# FFLF/ltx2 stage-2 pixel-frame budget (videoGen/renderArgs.js). Unset, PortOS
# scales it to detected unified memory. Raise it on a big-memory box; lower it if
# a render OOMs. This is the single cap both the worker and the client honour.
# FFLF_LTX2_PIXEL_BUDGET=8000000

# Megapixel ceiling for a local image regeneration render (imageGen/regen.js;
# default: 2.0). The result is upscaled back to the source's exact dimensions, so
# this bounds compute, not output size. Raise it on a high-memory machine.
# PORTOS_REGEN_MAX_MP=2.0

# 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 surviving retired trainer 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

# 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

# Music Video "Separate vocals" installs demucs into its own venv on first use
# (services/musicVideo/vocalSeparation.js; default: ~/.portos/venvs/demucs).
# PORTOS_DEMUCS_VENV_DIR=/path/to/venvs/demucs

# Music Video stem lyric alignment installs MMS_FA dependencies on first use
# (default: ~/.portos/venvs/lyric-align; Python 3.10–3.13, up to 3.12 on Intel Macs).
# PORTOS_LYRIC_ALIGN_VENV_DIR=/path/to/venvs/lyric-align

# Signal Desktop install directory read by Signal sync (signalSync.js; default:
# ~/Library/Application Support/Signal). SIGNAL_CONFIG_PATH and SIGNAL_DB_PATH are
# derived from it, so relocating a Signal install usually only needs this one.
# SIGNAL_DIR=/path/to/signal

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

# Signal sync SQLCipher database path (default: SIGNAL_DIR/sql/db.sqlite)
# SIGNAL_DB_PATH=/path/to/signal/sql/db.sqlite
#
# Capture opens that file read-only with the bundled SQLCipher driver
# (better-sqlite3-multiple-ciphers, SQLCipher 4 compatibility, raw 64-hex key)
# and exports a private plaintext snapshot so committed WAL frames are included.
# It never writes or checkpoints the live database or its WAL. Shipped prebuilds
# cover macOS, Linux (glibc and musl), and Windows, on x64 and arm64. If the
# prebuild cannot load, sync returns a setup error and leaves the cursor unchanged.

# Test/CI hook that supplies the "Signal Safe Storage" password instead of
# shelling out to the macOS keychain (signalSync.js). Leave unset on a real
# install — PortOS reads the keychain itself, and this would put a live
# credential in a plaintext file.
# SIGNAL_KEYCHAIN_PASSWORD=fake-keychain-password

# macOS Contacts (AddressBook) directory read by contact sync (contactsSync.js;
# default: ~/Library/Application Support/AddressBook)
# CONTACTS_AB_ROOT=/path/to/AddressBook

# macOS Messages database read by iMessage sync (imessageSync.js; default:
# ~/Library/Messages/chat.db)
# IMESSAGE_CHAT_DB=/path/to/chat.db

# 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>

# Set by AI Providers > Model host setup after successful dedicated setup.
# Restores the authenticated queue; the container restart policy restores Qwen.
# PORTOS_FLEET_LLM_ENABLED=0

# Claude Code config directory whose `projects/` transcripts feed the per-model
# token report on the Usage page (claudeCodeTranscriptUsage.js; default: ~/.claude)
# CLAUDE_CONFIG_DIR=/path/to/claude-config

# Root overrides for the file-system model stores listed under Models and System
# Resources (modelStoreStorage.js). Defaults: ~/.mtplx, ~/.cache/hy3dgen,
# <HF_HOME or ~/.cache/huggingface>/xet, ~/.pixie-forge
# MTPLX_HOME=/path/to/.mtplx
# HY3DGEN_MODELS=/path/to/hy3dgen
# HF_XET_CACHE=/path/to/xet
# PIXIE_FORGE_HOME=/path/to/.pixie-forge

# Music-video shots rendered at once in a final render (shotSegments.js;
# default: up to 4, fewer on a small machine). Each holds a film-look browser.
# PORTOS_MUSIC_VIDEO_SEGMENT_WORKERS=4