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

# Environment variables

This page lists every environment variable mads reads.

## mads settings

Each one is the environment form of a flag. A flag wins over its variable.

| Variable                   | Flag               | Description                                                                                   |
| -------------------------- | ------------------ | --------------------------------------------------------------------------------------------- |
| `MADS_PROVIDER`            | `--provider`       | Provider name.                                                                                |
| `MADS_MODEL`               | `--model`          | Model id.                                                                                     |
| `MADS_PLAN_MODEL`          | `--plan-model`     | Model for the plan mission.                                                                   |
| `MADS_BASE_URL`            | `--base-url`       | Endpoint for `openai-compat`.                                                                 |
| `MADS_FORMAT`              | `--format`         | `auto`, `pretty`, `plain`, `json` or `github`.                                                |
| `MADS_API_KEY`             | none               | Key for `openai-compat`. Optional.                                                            |
| `MADS_CLAUDE_BIN`          | none               | Path of the `claude` executable. Default `claude`.                                            |
| `MADS_CODEX_BIN`           | none               | Path of the `codex` executable. Default `codex`.                                              |
| `MADS_GEMINI_BIN`          | none               | Path of the `gemini` executable. Default `gemini`.                                            |
| `MADS_IMAGE_PROVIDER`      | `--image-provider` | `auto`, `gemini`, `openai` or `none`.                                                         |
| `MADS_IMAGE_MODEL`         | `--image-model`    | Image model name.                                                                             |
| `MADS_GEMINI_BASE_URL`     | none               | Endpoint of the Gemini image API. Default `https://generativelanguage.googleapis.com`.        |
| `MADS_OPENAI_BASE_URL`     | none               | Endpoint of the OpenAI image API. Default `https://api.openai.com`.                           |
| `MADS_ALLOW_PRIVATE_HOSTS` | none               | Any non-empty value lets `mads init` read loopback and private hosts. Local development only. |

mads has no variable for the turn, timeout, token or retry limits. Use the flags.

## Provider keys

mads reads the key from the provider's standard variable. An empty value counts as missing in `mads providers`.

| Provider        | Variable                  |
| --------------- | ------------------------- |
| `anthropic`     | `ANTHROPIC_API_KEY`       |
| `openai`        | `OPENAI_API_KEY`          |
| `gemini`        | `GEMINI_API_KEY`          |
| `openrouter`    | `OPENROUTER_API_KEY`      |
| `groq`          | `GROQ_API_KEY`            |
| `deepseek`      | `DEEPSEEK_API_KEY`        |
| `xai`           | `XAI_API_KEY`             |
| `ollama`        | none                      |
| `openai-compat` | `MADS_API_KEY` (optional) |

The image providers read the same keys: `gemini` reads `GEMINI_API_KEY` and `openai` reads `OPENAI_API_KEY`. With `--image-provider auto`, having one of them set is enough to turn image campaigns on.

## Agent CLIs

| Variable                  | Description                                                                                               |
| ------------------------- | --------------------------------------------------------------------------------------------------------- |
| `CLAUDE_CODE_OAUTH_TOKEN` | Login token for `claude` in CI. Create it with `claude setup-token`. mads does not read it. The CLI does. |
| `ANTHROPIC_API_KEY`       | Also read by `claude`. When set, mads runs claude in bare mode.                                           |

mads sets a few variables for the CLI process itself. `ENABLE_TOOL_SEARCH=false` for claude, `MADS_MCP_TOKEN` for codex, and `GEMINI_CLI_SYSTEM_SETTINGS_PATH` and `GEMINI_SYSTEM_MD` for gemini. You do not set them. See [Agent CLIs](/guides/agent-clis.md).

## Logging

| Variable   | Description                                                                        |
| ---------- | ---------------------------------------------------------------------------------- |
| `RUST_LOG` | A `tracing` filter such as `debug` or `mads_core=debug`. Overrides `-v` and `-vv`. |

## GitHub Actions

| Variable              | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| `GITHUB_ACTIONS`      | When `true`, `--format auto` picks `github`.                                           |
| `GITHUB_STEP_SUMMARY` | With the `github` format, mads appends `report.md` to this file when the run finishes. |


---

# 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, and the optional `goal` query parameter:

```
GET https://mads.avelino.run/reference/environment-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.