# Runtime environment variables

> Environment variables that configure Elide itself, such as ELIDE_HOME, ELIDE_LOG, ELIDE_ERROR_FORMAT and ELIDE_EDITOR, plus diagnostic variables and variables from other tools that Elide honors.

These variables configure Elide. Programs also see them in [`process.env`](https://elide.help/docs/env-variables).
For application dotenv files, Java properties, file selection, and encryption, see
[Environment and properties](https://elide.help/docs/environment).

| Variable | Purpose |
| --- | --- |
| `ELIDE_HOME` | Install directory for Elide versions. Default `$XDG_DATA_HOME/elide` or `~/.local/share/elide`. |
| `ELIDE_AUTO_INSTALL` | `1` downloads a pinned `.elideversion` without asking. |
| `ELIDE_LOCALE` | CLI locale, as `--locale`. |
| `ELIDE_LOG` | Log filter, e.g. `debug`. |
| `ELIDE_LOG_STYLE` | Log color: `auto`, `always`, or `never`. |
| `ELIDE_ERROR_FORMAT` | `plain` forces plain uncaught-error output, as `--error-format=plain`. |
| `ELIDE_REPL_HISTORY` | REPL history database. Default `~/.local/share/elide/repl/history.db` (Linux). |
| `ELIDE_EDITOR` | `code` or `idea` links error locations to VS Code or IntelliJ. Uses `EDITOR` if unset. |
| `ELIDE_CRASH_ROOT` | Directory for crash reports. |
| `ELIDE_AGENT` | `1` forces agent output; `0` turns agent detection off. See [AI Agents](https://elide.help/docs/agents). |
| `ELIDE_MCP_TOKEN` | Token for `elide mcp --mode http`. Random if unset. |
| `ELIDE_DEFER_EXIT` | Linux: `0` makes the process free its memory before it exits. |
| `ELIDE_SYS_TMP` | Set by Elide: the system temporary directory. |
| `ELIDE_HTTP_USER_AGENT` | `User-Agent` for `fetch`. Default `Elide/<version>`. |
| `ELIDE_HTTP_NATIVE_WORKERS` | `v2` transport workers for a server outside an application context (default cores ÷ 4, 1 to 8). `run`, `serve` and `dev` ignore it; their I/O threads follow the context count. |
| `ELIDE_NETTY_EVENT_LOOPS` | HTTP client and server I/O threads. Default `min(4, cores)`. |
| `ELIDE_TRANSPORT_V2` | `1`, `true`, `yes`, or `on` selects `--transport=v2` when no flag is given. |
| `ELIDE_HTTP_FALLBACK` | `v1` serves Unix domain socket requests through `nio`; `none` (default) fails them. |
| `NODE_TLS_REJECT_UNAUTHORIZED` | `0` disables TLS certificate checks for `fetch`. Warns once. |
| `NODE_USE_SYSTEM_CA` | `1` trusts the system certificate store for `fetch`. |
| `NODE_EXTRA_CA_CERTS` | PEM file of extra CA certificates for `fetch`. |
| `ELIDE_MAVEN_TLS_EXTRA_CA` | PEM file of extra CA certificates for Maven downloads. |
| `ELIDE_MAVEN_<NAME>_USERNAME`, `ELIDE_MAVEN_<NAME>_PASSWORD` | Credentials for `elide publish --to <NAME>`; `<NAME>` is the repository name uppercased with other characters turned to `_`. See [Maven publishing](https://elide.help/docs/toolchain/jvm/publishing). |
| `ELIDE_GPG_PASSPHRASE` | Passphrase for `elide publish` to sign with `gpg` in CI. See [Maven publishing](https://elide.help/docs/toolchain/jvm/publishing). |
| `ELIDE_PKGST_NPM_ENDPOINT` | npm proxy URL for `--pkgst`. Default `https://npm.pkg.st`. |
| `ELIDE_PKGST_PYPI_ENDPOINT` | PyPI proxy URL for `--pkgst`. Default `https://pypi.pkg.st`. |
| `ELIDE_REMOTE_CACHE` | Shared build cache URL. See [Build cache](https://elide.help/docs/toolchain/build-tasks#build-cache). |
| `ELIDE_REMOTE_CACHE_TOKEN` | Bearer token for the shared cache. |
| `ELIDE_REMOTE_CACHE_USERNAME` | Basic-auth user for the shared cache. |
| `ELIDE_REMOTE_CACHE_PASSWORD` | Basic-auth password for the shared cache. |
| `ELIDE_REMOTE_CACHE_POLICY` | `eager` (default) or `smart`. |
| `ELIDE_REMOTE_CACHE_PULL` | `false` stops downloads from the shared cache. |
| `ELIDE_REMOTE_CACHE_PUSH` | `false` stops uploads to the shared cache. |
| `ELIDE_BUILD_TELEMETRY` | `1`, a file, or a directory writes a build trace ([Build Tasks](https://elide.help/docs/toolchain/build-tasks)). |
| `ELIDE_KOTLINC_ABI_STRIP` | `0` makes `kotlinc --abi-only` keep full code generation instead of stripping function bodies. |
| `ELIDE_WORKER_CLASSPATH_CACHE` | `0` turns `javac --classpath-cache` off. |
| `ELIDE_WORKER_CLASSPATH_CACHE_MAX_HANDLES` | Most classpath JARs `javac --classpath-cache` keeps open. Default one per MiB of heap, between 512 and 65536. |

## Configuration decryption keys

Elide 1.6.2 accepts dotenvx-compatible encrypted values in dotenv and Java properties files.

| Variable | Purpose |
| --- | --- |
| `DOTENV_PRIVATE_KEY` | Private key for decrypting `encrypted:` configuration values. |
| `DOTENV_PRIVATE_KEY_*` | Additional named private keys, such as `DOTENV_PRIVATE_KEY_PRODUCTION`. A suffix does not select a configuration file. |

Supply keys through the inherited environment or `.env.keys` beside selected configuration sources.
Inherited assignments override matching names in key files. Key files are read only when an effective encrypted value
requires decryption; their entries are not exported as application configuration. Inherited key variables retain
ordinary inherited-environment visibility. Do not put private-key assignments in application dotenv or properties
files: Elide rejects them. `DOTENV_PUBLIC_KEY*` configuration entries are metadata and are omitted from loaded values.

Keep `.env.keys` out of version control and use your CI secret store for inherited keys. See
[Encrypted values](https://elide.help/docs/environment#encrypted-values) for file lookup order, supported formats, and examples.

## Diagnostics

| Variable | Purpose |
| --- | --- |
| `ELIDE_ENGINE_LOG` | Print low-level runtime log records to stderr. |
| `ELIDE_DIAG_STARTUP` | Print startup phase timings to stderr. |
| `ELIDE_TRANSPORT_DIAGNOSTICS` | `1` prints network transport statistics to stderr. |
| `ELIDE_TRACE_PROCESSORS` | `1` prints each Java annotation processor class to stderr as it loads. |

## Variables from other tools

| Variable | Read by | Purpose |
| --- | --- | --- |
| `LANGUAGE`, `LC_ALL`, `LC_MESSAGES`, `LANG` | CLI | Locale when `ELIDE_LOCALE` is unset, first one set wins. Give a region (`fr_FR.UTF-8`); a bare language such as `fr` is ignored. |
| `JDK_JAVAC_OPTIONS` | `elide javac` | Extra `javac` options, as with the JDK's `javac`. Output then uses `javac`'s own format. |
| `DOCKER_CONFIG` | Container builds | Directory of the Docker `config.json` whose `auths`, `credHelpers` and `credsStore` supply registry credentials. Default `~/.docker`. |
| `UV_DEFAULT_INDEX`, `UV_INDEX_URL` | Python installs | PyPI index; when set, `--pkgst` leaves it unchanged. |
| `NODE_REDIRECT_WARNINGS` | JavaScript | Append process warnings to this file instead of stderr. |

## OpenTelemetry variables

Elide reads the standard OpenTelemetry variables. They override the [`opentelemetry` block](https://elide.help/docs/elide-pkl-reference#opentelemetry-block)
and are overridden by `--otel-*` flags; see [Configuration](https://elide.help/docs/opentelemetry/configuration). Invalid values are ignored.

| Variable | Purpose |
| --- | --- |
| `OTEL_SDK_DISABLED` | `true` turns telemetry off. |
| `OTEL_SERVICE_NAME` | `service.name`. |
| `OTEL_RESOURCE_ATTRIBUTES` | Extra resource attributes, `key=value,...` (percent-encoded values). |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | Base URL; `/v1/<signal>` is appended for HTTP. Creates an `otlp` destination if none exists. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc`, `http/protobuf` (default), or `http/json`. |
| `OTEL_EXPORTER_OTLP_HEADERS` | Request headers, `key=value,...`. Treated as secrets. |
| `OTEL_EXPORTER_OTLP_COMPRESSION` | `gzip` (default) or `none`. |
| `OTEL_EXPORTER_OTLP_TIMEOUT` | Request timeout in milliseconds. Default `10000`. |
| `OTEL_EXPORTER_OTLP_CERTIFICATE` | PEM file of trusted certificates, replacing the system trust store. |
| `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`, `OTEL_EXPORTER_OTLP_CLIENT_KEY` | PEM client certificate chain and private key for mutual TLS. Set both. |
| `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_*` | Per-signal `ENDPOINT` (used as given), `PROTOCOL`, `HEADERS`, `COMPRESSION`, `TIMEOUT`, `CERTIFICATE`, `CLIENT_CERTIFICATE`, `CLIENT_KEY`. |
| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | `always_on`, `always_off`, `traceidratio`, or `parentbased_*` (default `parentbased_always_on`), and the ratio. |
| `OTEL_PROPAGATORS` | `tracecontext`, `baggage`, or `none`, for the OpenTelemetry API in applications. Default `tracecontext,baggage`. Does not turn on baggage for Elide's HTTP server and clients. |
| `OTEL_METRIC_EXPORT_INTERVAL` | Metric export interval in milliseconds. Default `60000`. |
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | `cumulative` (default) or `delta`. |
| `OTEL_METRICS_EXEMPLAR_FILTER` | `trace_based` (default: measurements inside a sampled span), `always_on`, or `always_off`. |
| `OTEL_SEMCONV_EXCEPTION_SIGNAL_OPT_IN` | `logs` records exceptions as log records only; `logs/dup` (default) also adds `exception` span events. |
| `OTEL_{TRACES,METRICS,LOGS}_EXPORTER` | `none` turns that signal off, for applications and Elide alike. `otlp` with no destination configured sends that signal to `http://localhost:4318` (`4317` for gRPC). |

`OTEL_EXPORTER_OTLP_*` apply to every destination using the `otlp` provider. Elide adds a shorthand
for the [provider presets](https://elide.help/docs/elide-pkl-reference#opentelemetry-block):

| Variable | Purpose |
| --- | --- |
| `ELIDE_OTEL_PROVIDER` | Adds a destination for a provider: `otlp`, `sentry`, `datadog`, `posthog`, `honeycomb`, or `grafana`. |
| `ELIDE_OTEL_REGION` | Provider site or region, e.g. `us5` (Datadog), `eu` (PostHog, Honeycomb), `prod-us-east-0` (Grafana). |
| `ELIDE_OTEL_SIGNALS` | Signals for that destination, e.g. `traces,logs`. Default: the provider's default signals. |
| `ELIDE_OTEL_BAGGAGE_INBOUND` | `true` admits served requests' `baggage` headers. Default `false`. |
| `ELIDE_OTEL_BAGGAGE_OUTBOUND` | `true` sends the current baggage on outgoing HTTP requests. Default `false`. |
| `ELIDE_OTEL_BAGGAGE_ALLOW` | Comma-separated baggage keys allowed in both directions. Default: all keys. |
| `ELIDE_OTEL_PROFILES` | `true` samples guest CPU profiles at 100 per second, or set a frequency such as `49`. Default off. |
| `ELIDE_OTEL_RUNTIME_INTERNAL_TRACES` | `true` includes high-volume library spans such as Compio task polls. Requires runtime tracing and a configured destination. Default `false`. |

Provider credentials come from their usual variables: `SENTRY_DSN`, `DD_API_KEY` (and `DD_SITE`),
`POSTHOG_PROJECT_TOKEN`, `HONEYCOMB_API_KEY`, and `GRAFANA_CLOUD_OTLP_CREDENTIAL` (`<instance id>:<token>`).

```sh
ELIDE_OTEL_PROVIDER=honeycomb HONEYCOMB_API_KEY=... elide serve app.ts
```