# Environment variables

> Every environment variable read by elelem core and its plugins, with defaults.


elelem has no config file. Settings that are not command-line options are environment variables, and most belong to a plugin. This is every variable read by core and the plugin gems, found by searching each repository for `ENV` and `getenv`.

"Required" means the provider stops with an error when the variable is missing. "Build" means the variable is read when the gem's native extension compiles, during `gem install`, not at run time.

| Variable | Read by | Default | What it does |
|---|---|---|---|
| `ELELEM_LOG_LEVEL` | `elelem`, `elelem-llama` | `warn` | Log level for messages on stderr: `debug`, `info`, `warn`, `error`, or `fatal`. `elelem-llama` applies it to llama.cpp's own log too. |
| `ELELEM_CMD_TIMEOUT` | `elelem-builtins` | none | Seconds before an `execute` command is stopped with TERM, then KILL half a second later. The result notes the timeout and reports exit status 124. Unset means no limit. |
| `XDG_STATE_HOME` | `elelem-builtins` | `~/.local/state` | Session transcripts are written to `elelem/sessions/` under this directory. |
| `ANTHROPIC_API_KEY` | `elelem-anthropic` | required for `-p anthropic` | API key, sent as `x-api-key`. |
| `ANTHROPIC_MODEL` | `elelem-anthropic` | `claude-opus-4-5-20250514` | Model for `-p anthropic` when `--model` is not given. |
| `VERTEX_MODEL` | `elelem-anthropic` | `claude-opus-4-5@20251101` | Model for `-p vertex` when `--model` is not given. |
| `GOOGLE_CLOUD_PROJECT` | `elelem-anthropic` | required for `-p vertex` | Google Cloud project for Vertex AI. The access token comes from `gcloud auth application-default print-access-token`. |
| `GOOGLE_CLOUD_REGION` | `elelem-anthropic` | `us-east5` | Vertex AI region. |
| `OPENAI_API_KEY` | `elelem-openai` | required | API key, sent as a bearer token. |
| `OPENAI_MODEL` | `elelem-openai` | `gpt-4o` | Model when `--model` is not given. |
| `OLLAMA_HOST` | `elelem-ollama` | `localhost:11434` | Host and port of the Ollama server. |
| `OLLAMA_MODEL` | `elelem-ollama` | `gpt-oss:latest` | Model when `--model` is not given. |
| `OLLAMA_THINK` | `elelem-ollama` | none | Sent as the `think` field of each request. |
| `OLLAMA_KEEP_ALIVE` | `elelem-ollama` | none | Sent as the `keep_alive` field of each request. |
| `ELELEM_GGUF_MODEL` | `elelem-llama`, `elelem-ggml` | `~/.agents/models/default.gguf`, or the only `.gguf` file there | Path to the GGUF model. For `elelem-llama`, `--model` takes precedence. |
| `ELELEM_GGUF_N_CTX` | `elelem-llama` | `0` | Context size in tokens. `0` uses the model's training context, capped at 65,536. If that does not fit in memory, it halves the size down to 4,096. |
| `ELELEM_GGUF_N_GPU_LAYERS` | `elelem-llama` | `999` or `0` | Layers to put on the GPU. Default is `999` (all) on a Vulkan, CUDA, or Apple Silicon Metal build when the model file is under 80% of free GPU memory, otherwise `0`. |
| `ELELEM_GGUF_MAX_TOKENS` | `elelem-llama`, `elelem-ggml` | `0` (llama), `256` (ggml) | Most tokens to generate per reply. For `elelem-llama`, `0` means the rest of the context. |
| `ELELEM_GGUF_TEMP` | `elelem-llama` | `0.7` | Sampling temperature. `0` or below means greedy decoding. |
| `ELELEM_GGUF_SEED` | `elelem-llama` | `-1` | Sampling seed. |
| `ELELEM_TOP_K` | `elelem-llama` | `40` | Top-k sampling. Ignored when decoding is greedy. |
| `ELELEM_TOP_P` | `elelem-llama` | `0.95` | Top-p sampling. Ignored when decoding is greedy. |
| `ELELEM_REPEAT_LAST_N` | `elelem-llama` | `0` | Tokens to look back for the repeat penalty. `0` turns the penalty off. |
| `ELELEM_REPEAT_PENALTY` | `elelem-llama` | `1.0` | Repeat penalty. `1.0` is no penalty. |
| `ELELEM_KV_CACHE_TYPE` | `elelem-llama` | `q8_0` | KV cache type: `f16`, `f32`, `q4_0`, or `q8_0`. Anything else means `q8_0`. |
| `ELELEM_LLAMA_BACKEND` | `elelem-llama` (build) | `auto` | GPU backend to compile: `cpu`, `vulkan`, `cuda`, `hip`, or `metal`. `auto` picks Metal on macOS, then CUDA if `nvcc` is found, Vulkan if `glslc` and the Vulkan loader are found, HIP if `hipcc` and a GPU target are found, else CPU. |
| `ELELEM_HIP_ARCH` | `elelem-llama` (build) | detected, else `gfx1100` | AMD GPU target for a HIP build. |
| `ELELEM_CANDLE_MODEL` | `elelem-candle` | required | A safetensors directory or a Hugging Face repo id. |
| `ELELEM_CANDLE_DEVICE` | `elelem-candle` | `cpu` | Device name passed to Candle. |
| `ELELEM_LLAMA2_CHECKPOINT` | `elelem-llama2` | required | Path to a llama2.c `.bin` checkpoint. |
| `ELELEM_LLAMA2_TOKENIZER` | `elelem-llama2` | the gem's bundled `tokenizer.bin` | Path to the tokenizer. |
| `ELELEM_LLAMA2_STEPS` | `elelem-llama2` | `0` | Most tokens to generate. `0` means the model's full sequence length. |
| `ELELEM_LLAMA2_TEMP` | `elelem-llama2` | `1.0` | Sampling temperature. |
| `ELELEM_LLAMA2_TOPP` | `elelem-llama2` | `0.9` | Top-p sampling. |
| `ELELEM_LLAMA2_SEED` | `elelem-llama2` | `-1` | Sampling seed. |
| `ELELEM_SD_IMAGE_MODEL` | `elelem-diffusion` | none | Stable Diffusion model for the `image` tool. The tool returns an error while it is unset. |
| `ELELEM_SD_VIDEO_MODEL` | `elelem-diffusion` | none | Diffusion model for the `video` tool. Required by that tool. |
| `ELELEM_SD_VIDEO_VAE` | `elelem-diffusion` | none | VAE for the `video` tool. Required by that tool. |
| `ELELEM_SD_VIDEO_T5XXL` | `elelem-diffusion` | none | T5-XXL text encoder for the `video` tool. Required by that tool. |
| `ELELEM_SD_ESRGAN_MODEL` | `elelem-diffusion` | none | ESRGAN model for the `upscale` tool. Required by that tool. |
| `ELELEM_PROVIDER` | `elelem-server`, `elelem-evals` | `stub` (server), `llama` (evals) | Provider when `-p` is not given. The `elelem` command does not read it. |
| Any `${NAME}` in `mcp.json` | `elelem-mcp` | required when referenced | Substituted into a server's `env` and `headers`. A missing variable is an error for that server. |
| `CC` | `elelem-ggml`, `elelem-llama2` (build) | `cc` | C compiler. |
| `CXX` | `elelem-llama`, `elelem-llama2`, `elelem-diffusion` (build) | `c++` | C++ compiler. |

The build scripts of `elelem-llama` and `elelem-ratatui` also search `PATH` for build tools: `nvcc`, `glslc`, `hipcc`, and `vulkaninfo` for llama, `cargo` for ratatui. Paths under `~` are resolved through `HOME`.

## Setting them

For one command:

```bash
ELELEM_LOG_LEVEL=debug elelem ask -p ollama "hello"
```

For every session, export them from your shell profile:

```bash
export ANTHROPIC_API_KEY=your-key
export ELELEM_CMD_TIMEOUT=120
```

`--model` on the command line wins over the provider's model variable for `anthropic`, `vertex`, `openai`, `ollama`, and `llama`.


Canonical: https://elelem.sh/docs/environment/