Skip to main content
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"
    }
  }
}
FieldMeaning
workingDirCodex working directory (relative paths resolve from Stack app root)
defaultEnvironmentInitial dev/staging/prod selection
environments.*.apiBaseUrlSynth API base for remote ops
environments.*.authEnvEnvironment variable name for the API key
authEnvFileOptional 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.

​
Codex harness

EnvDefaultPurpose
STACK_HARNESScodexAgent harness (codex or cursor)
STACK_CODEX_COMMANDcodexPath to Codex binary
STACK_CODEX_MODELfrom ~/.codex/config.tomlOverride model
STACK_CODEX_REASONING_EFFORTfrom configOverride effort
See Quickstart § Configure with Codex.

​
stackd

EnvDefault
STACK_API_URLhttp://127.0.0.1:8792
STACK_API_BIND127.0.0.1
STACK_API_PORT8792
STACKD_MCP1 (set 0 to disable HTTP MCP)

​
Monitor

EnvPurpose
STACK_MONITOR_ENABLED0 disables monitor
STACK_MONITOR_PROFILEe.g. progress-narrator
STACK_MONITOR_STRICTNESSpassive / 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:
EnvEffect
STACK_AUTO_START=0Disable all auto-start
STACK_AUTO_START_LOCAL_OPTIMIZER=0Disable GEPA auto-start only
Logs: .stack/bootstrap/dev-slot.log, .stack/optimizers/gepa-service.log.

​
Telemetry

Opt out anytime: 
stack telemetry off
# or: STACK_TELEMETRY=0 / DO_NOT_TRACK=1
Details: Quickstart § Telemetry.

​
Next