# Environment variables

> The environment variables you can set, and the ones Luxe sets.

An environment variable wins over the same setting in a config file, and a command-line flag wins
over both. A variable that turns something off, such as `LUXE_HERDR=0`, cannot turn back on what a
config file turned off.

## Model and provider

| Variable | Default | Does |
| --- | --- | --- |
| `LUXE_MODEL` | | The model, as an ID or `provider/id` |
| `LUXE_PROVIDER` | | The provider |
| `LUXE_API_KEY` | | A key for the provider the session starts on |
| `LUXE_BASE_URL` | | That provider's endpoint, including its version |
| `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, … | | Each provider's own key; see [Models and providers](providers.md#providers) |
| `LUXE_STREAM_START_TIMEOUT` | `60` | Seconds to wait for a reply to start. `0` waits forever. |
| `LUXE_STREAM_IDLE_TIMEOUT` | `180` | Seconds a reply may go quiet. `0` waits forever. |
| `LUXE_PROVIDER_RETRIES` | `3` | Tries after the first when a provider fails before answering |
| `LUXE_COPILOT_PLAN_USAGE` | `1` | `0` stops reading how much of your GitHub Copilot plan is used |

## Files

| Variable | Does |
| --- | --- |
| `LUXE_CONFIG_DIR` | Where configuration and credentials live, instead of `~/.config/luxe` |
| `LUXE_STATE_DIR` | Where Luxe keeps its state, such as the model you last chose, MCP sign-ins and the logs of commands that only report, instead of `~/.local/state/luxe` |
| `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME` | Honored on every platform; see [Install](install.md#where-luxe-keeps-files) |

When Luxe works out where its files go, a path in one of these, or in `HOME`, that is not valid
UTF-8 is ignored, as if the variable were unset.

## Model catalog

| Variable | Default | Does |
| --- | --- | --- |
| `LUXE_MODELS_DEV_REFRESH` | | `0` never refreshes, and the built-in catalog still works. `1` refreshes at every start. Unset refreshes once the copy is older than `LUXE_MODELS_DEV_TTL`. |
| `LUXE_MODELS_DEV_URL` | `https://models.dev/api.json` | Refresh from a mirror, as a full URL |
| `LUXE_MODELS_DEV_PATH` | | Keep the catalog in this file. The refresh writes there too, so pair it with `LUXE_MODELS_DEV_REFRESH=0` to pin a file of your own. |
| `LUXE_MODELS_DEV_TTL` | `21600` | Seconds between refreshes |

## Tools and turns

| Variable | Default | Does |
| --- | --- | --- |
| `LUXE_TOOL_TIMEOUT_SECS` | | Replace the time limit of every tool that has one |
| `LUXE_MAX_TOOL_ITERATIONS` | | Most rounds of tool calls in one turn. `0` lifts a configured cap. |
| `LUXE_COMPRESS` | `1` | `0` stops trimming long command output, though output past the size limit is still cut |
| `LUXE_LSP_ON_EDIT` | `1` | `0` stops adding language server errors, and notes about missing tests, after edits |
| `LUXE_SIZE_CHECK` | `1` | `0` stops telling the agent when an edit takes a file past 500 lines or a function past 20 |
| `LUXE_DEBUG_NUDGE` | `1` | `0` stops suggesting the debugger after repeated test failures |
| `LUXE_PLAN_NUDGE` | `1` | `0` stops reminding the agent to update its checklist |
| `LUXE_LAZY_TOOLS` | `1` | `0` sends every tool's description with every request |
| `LUXE_CORE_TOOLS` | | The tools sent with every request, comma-separated; the rest load when needed |
| `LUXE_DAP_STOP_TIMEOUT_SECS` | `30` | How long the debugger waits for a program to stop |
| `LUXE_MAX_DEPTH` | `2` | How deeply Luxe may run inside itself, as with [subagents](recipes.md#subagents) |
| `LUXE_WEB_ALLOW_PRIVATE` | | `1` lets `web_fetch` and `screenshot` reach your local network and files |
| `LUXE_WEB_TIMEOUT_SECS` | `30` | How long one fetch may take. Past 60, raise `LUXE_TOOL_TIMEOUT_SECS` too. |
| `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `FIRECRAWL_API_KEY` | | Search providers, and Firecrawl for pages built with JavaScript; see [Tools](tools.md#web) |

## Integrations

| Variable | Does |
| --- | --- |
| `LUXE_EDITOR`, then `VISUAL`, then `EDITOR` | The editor Luxe opens files in |
| `LUXE_FILE_MANAGER`, then `FILE_MANAGER` | The file manager `O` in the dock's file tree opens a folder in. Without either, the first of yazi, lf, ranger and nnn that is installed, then your desktop's own. |
| `LUXE_HERDR` | `0` stops reporting state to [Herdr](recipes.md#run-luxe-in-herdr) |
| `LUXE_UPDATE_CHECK` | `0` turns off the update check |

## Diagnostics

| Variable | Does |
| --- | --- |
| `LUXE_LOG` | What goes in the log, such as `debug` or `luxe_core=debug`. `RUST_LOG` works too. See [Logs](troubleshooting.md#logs). |
| `LUXE_WIRE_LOG` | A file to record every request sent to the model; see [Troubleshooting](troubleshooting.md#see-what-is-sent-to-the-model) |

## Set by Luxe

| Variable | Is |
| --- | --- |
| `LUXE_DEPTH` | How deeply this run is nested inside another Luxe |
| `LUXE_REVIEW_GATE_ACTIVE` | Set for a loop's [gate commands](loop.md#check-each-phase), so a Luxe they start does not run a gate of its own |
| `LUXE_HANDOFF` | For a [launcher](configuration.md#launchers): a file whose contents go in the composer when the program exits |