Configuration

Stack config, working directory, environments, and common environment variables.

Documents Stack 0.2.0-dev.20260701.1. Monitor and telemetry env vars added in the 2026-07-01 release.

Stack reads stack.config.json from the install / repo root. Override the working directory per run when Codex should operate in a different project tree.

Example stack.config.json

{
  "workingDir": "..",
  "defaultEnvironment": "dev",
  "environments": {
    "dev": {
      "label": "Dev",
      "apiBaseUrl": "http://127.0.0.1:8000",
      "authEnv": "SYNTH_API_KEY",
      "optimizerDbPath": ".stack/optimizers/gepa-service.sqlite",
      "optimizerServiceUrl": "http://127.0.0.1:8879"
    },
    "staging": {
      "label": "Staging",
      "apiBaseUrl": "https://staging-api.usesynth.ai",
      "authEnv": "SYNTH_STAGING_API_KEY"
    },
    "prod": {
      "label": "Prod",
      "apiBaseUrl": "https://api.usesynth.ai",
      "authEnv": "SYNTH_API_KEY"
    }
  }
}

Field	Meaning
workingDir	Codex working directory (relative paths resolve from Stack app root)
defaultEnvironment	Initial dev/staging/prod selection
environments.*.apiBaseUrl	Synth API base for remote ops
environments.*.authEnv	Environment variable name for the API key
authEnvFile	Optional file path to load keys (preferred over committing secrets)

One-run override:

STACK_WORKING_DIR=/path/to/workspace stack

Stack passes --skip-git-repo-check to Codex by default so parent workspaces (e.g. ~/Documents/GitHub) work even when they are not a single git repo.

API keys

Create keys at usesynth.ai/keys.

export SYNTH_API_KEY="sk_..."
stack doctor

Hosted SMR, Factory, and hosted optimizers require auth. Local demo, doctor, and local GEPA work without signup.

See Local-only mode for the signed-out contract and Connect Synth for hosted unlocks.

Codex harness

Env	Default	Purpose
STACK_HARNESS	codex	Agent harness (codex or cursor)
STACK_CODEX_COMMAND	codex	Path to Codex binary
STACK_CODEX_MODEL	from ~/.codex/config.toml	Override model
STACK_CODEX_REASONING_EFFORT	from config	Override effort

See Quickstart § Configure with Codex.

Stackd

Env	Default
STACK_API_URL	http://127.0.0.1:8792
STACK_API_BIND	127.0.0.1
STACK_API_PORT	8792
STACKD_MCP	1 (set 0 to disable HTTP MCP)

Monitor

Env	Purpose
STACK_MONITOR_ENABLED	0 disables monitor
STACK_MONITOR_PROFILE	e.g. progress-narrator
STACK_MONITOR_STRICTNESS	passive / conservative / aggressive

See Goal mode & monitor.

Local GEPA auto-start

On dev, Stack can auto-start synth-optimizers gepa service when the local optimizer is installed:

Env	Effect
STACK_AUTO_START=0	Disable all auto-start
STACK_AUTO_START_LOCAL_OPTIMIZER=0	Disable GEPA auto-start only

Logs: .stack/bootstrap/dev-slot.log, .stack/optimizers/gepa-service.log.

Telemetry

Basic DAU is on by default and can be turned off. Advanced product telemetry requires an explicit TUI approval.

stack telemetry digest

In the TUI, use /settings telemetry to turn basic DAU off or accept/decline advanced telemetry. For local development, STACK_TELEMETRY=0 disables local product telemetry emission.

Details: Quickstart § Telemetry.

Next

• Cockpit controls
• stackd