> For the complete documentation index, see [llms.txt](https://docs.fritesai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fritesai.com/reference/environment-variables.md).

# Environment variables

frites is configured primarily through its [config file](/reference/configuration.md). Environment variables cover process-level knobs (host, port, auth) and a few overrides. This page lists **only** variables that are actually read in the frites source.

The variables fall into three groups:

1. [Consumed by frites](#consumed-by-frites): read by frites' own code.
2. [Set by you, read by Codex](#set-by-you-read-by-codex-frites_key): the Codex `env_key` label.
3. [Evaluation-only](#evaluation-only): used by the benchmark harness, documented elsewhere.

## Consumed by frites

These are read in frites' source. Most have a config-file equivalent; where the env var and config overlap, the env var wins for that process.

### Gateway process

| Variable                 | Default                     | Effect                                                                                                                                                                |
| ------------------------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FRITES_GATEWAY_HOST`    | `127.0.0.1`                 | Bind address for the gateway server. Loopback-only by default.                                                                                                        |
| `FRITES_GATEWAY_PORT`    | `6767`                      | Bind port for the gateway server.                                                                                                                                     |
| `FRITES_GATEWAY_TOKEN`   | *(unset)*                   | Optional shared secret. When set, inbound requests must present it via `Authorization: Bearer …` or `x-api-key`; otherwise the gateway returns `401`. Off by default. |
| `FRITES_HEARTBEAT_MS`    | `5000`                      | How often (ms) to emit a `still working — Ns` heartbeat to the client during a long turn.                                                                             |
| `FRITES_TELEMETRY_MS`    | `2000`                      | How often (ms) to refresh the per-agent `~N tok · Ns` telemetry line while a child streams.                                                                           |
| `FRITES_PROGRESS_DETAIL` | *(config `progressDetail`)* | Per-agent progress verbosity: `telemetry` or `interleaved`. Overrides `config.progressDetail` when set.                                                               |

See the [Gateway API](/reference/gateway-api.md) page for how host/port/token affect the server, and [cost telemetry](/concepts/cost-telemetry.md) for the heartbeat/telemetry lines.

### Logging

| Variable           | Default                            | Effect                                                                                 |
| ------------------ | ---------------------------------- | -------------------------------------------------------------------------------------- |
| `FRITES_LOG_LEVEL` | *(config `logLevel`, else `info`)* | Gateway log verbosity: `debug`, `info`, `warn`, `error`. The env var wins over config. |
| `FRITES_LOG_JSON`  | *(unset)*                          | Set to `1` for newline-delimited JSON log lines instead of the human format.           |

See [logging](/reference/logging.md) for the full logging model.

### Auth / key passthrough

| Variable                  | Default                  | Effect                                                                                                                                                                                                                  |
| ------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FRITES_PASS_API_KEYS`    | *(config `passApiKeys`)* | Set to `1` to forward `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` through to child agents (metered API mode). Subscription-first by default: keys are withheld so CLIs use OAuth. Read by the gateway, MCP, and CLI.         |
| `ANTHROPIC_API_KEY`       | *(unset)*                | Forwarded to children **only** when `passApiKeys` is on. Otherwise withheld.                                                                                                                                            |
| `OPENAI_API_KEY`          | *(unset)*                | Forwarded to children **only** when `passApiKeys` is on. Otherwise withheld.                                                                                                                                            |
| `CLAUDE_CODE_OAUTH_TOKEN` | *(unset)*                | Headless Claude subscription token (from `claude setup-token`). On the [child allowlist](#child-environment), so it reaches children. This is how Claude auths where the macOS Keychain is unavailable (containers/CI). |

The child auth and billing model is the canonical topic of [auth and billing](/product/auth-and-billing.md).

### Config resolution

| Variable               | Default   | Effect                                                                          |
| ---------------------- | --------- | ------------------------------------------------------------------------------- |
| `FRITES_GLOBAL_CONFIG` | *(unset)* | Override the path to the global config file (normally `~/.frites/config.json`). |

### Child environment

These are managed by frites' env sandbox (`packages/agents/src/env-sandbox.ts`). You do not normally set them yourself, but they are part of the contract.

| Variable       | Role                                                                                                                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FRITES_DEPTH` | Recursion fuse. The parent reads it (default `0`); each child is launched with `depth + 1`. When it would reach `maxDepth`, frites refuses to spawn, preventing a child from invoking frites again. |
| `FRITES_CHILD` | Set to `1` in every spawned child environment, marking it as a frites-launched child.                                                                                                               |

Child environments are built by **allowlist**, never by copying `process.env`. The allowlist that is carried through (when present) is: `HOME`, `PATH`, `LANG`, `LC_ALL`, `LC_CTYPE`, `LC_MESSAGES`, `TERM`, `USER`, `LOGNAME`, `SHELL`, `TMPDIR`, `TZ`, `CODEX_HOME`, `XDG_CONFIG_HOME`, `XDG_CACHE_HOME`, `XDG_DATA_HOME`, and `CLAUDE_CODE_OAUTH_TOKEN`. See the [isolation architecture](/architecture/isolation.md) and [safety model](/product/safety-model.md).

### Provider base-URL variables (scrubbed)

To prevent a child from pointing back at the gateway (a recursive fork-bomb), frites **scrubs** these base-URL variables out of every child environment, even if reintroduced via `extraEnv`:

* `ANTHROPIC_BASE_URL`
* `ANTHROPIC_API_URL`
* `OPENAI_BASE_URL`
* `OPENAI_API_BASE`
* `CODEX_BASE_URL`

`ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` are still meaningful **on the host side**: they are what you set in `~/.claude/settings.json` to point Claude Code at the gateway (`ANTHROPIC_BASE_URL=http://127.0.0.1:6767`, `ANTHROPIC_AUTH_TOKEN=frites`). frites only scrubs them from the **child** environment it spawns. See [configure Claude Code](/getting-started/configure-claude-code.md).

## Set by you, read by Codex (`FRITES_KEY`)

`FRITES_KEY` is **not read by frites.** It is the variable named in Codex's `env_key` setting: you set it (`export FRITES_KEY=frites`), and Codex reads it to populate the auth token it presents to the gateway. It is documented here only because the Codex setup mentions it.

```toml
# ~/.codex/config.toml
model_provider = "frites"
[model_providers.frites]
base_url = "http://127.0.0.1:6767/v1"
wire_api = "responses"
env_key = "FRITES_KEY"
```

Whatever you export as `FRITES_KEY` is the token Codex sends; if you have set `FRITES_GATEWAY_TOKEN` on the gateway, `FRITES_KEY` must match it. See [configure Codex](/getting-started/configure-codex.md).

## Evaluation-only

The benchmark harness under `eval/` uses its own `FRITES_BENCH_*` and `AIDER_*` variables (e.g. `FRITES_BENCH_HARNESS`, `FRITES_BENCH_URL`, `FRITES_BENCH_GATEWAY_HOST`, `AIDER_REPO`, `AIDER_EDIT_FORMAT`). These are not part of the runtime product and are not duplicated here. See the evaluation runbook at [../../eval/README.md](https://github.com/whatl3y/frites/blob/main/eval/README.md) and [evaluation](/development/evaluation.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fritesai.com/reference/environment-variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.