> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> stack.config.json, working directory, environments, and common environment variables.

<Note>
  Documents Stack **`0.2.0-dev.20260701.1`**. Monitor and telemetry env vars added in
  the [2026-07-01 release](/stack/changelog).
</Note>

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`

```json theme={null}
{
  "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:

```bash theme={null}
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](https://usesynth.ai/keys).

```bash theme={null}
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

| 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](/stack/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](/stack/goal-mode).

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

Opt out anytime:

```bash theme={null}
stack telemetry off
# or: STACK_TELEMETRY=0 / DO_NOT_TRACK=1
```

Details: [Quickstart § Telemetry](/stack/quickstart#telemetry).

## Next

* [Cockpit controls](/stack/cockpit)
* [stackd](/stack/stackd)