Environment variables
Every LPM_* variable LPM reads, what it does, and when to use it.
LPM reads a number of environment variables to override behavior, route auth, or expose diagnostic knobs. Most users never need to touch these — they exist for CI, debugging, and uncommon workflows.
Variables are grouped by purpose. Anything marked diagnostic is a debug-only escape hatch — not a stable, documented user knob.
| Variable | Effect |
|---|
LPM_TOKEN | Use this token instead of the OS-keychain-stored token. Equivalent to the global --token <T> flag. Useful in CI. |
LPM_REGISTRY_URL | Override the registry URL. Equivalent to --registry <URL>. |
LPM_OIDC_TOKEN | Canonical pre-supplied OIDC token for registry-exchange surfaces — lpm setup ci --oidc, the lpm publish auto-exchange path, and lpm env pull --oidc. The audience must be https://lpm.dev (the snippet emitted by lpm ci setup gitlab mints it correctly via the id_tokens block). When set, the bypass takes precedence over the GitHub Actions runtime fetch, so self-hosted runners can opt out of the runtime call. Does not affect lpm publish --provenance — Sigstore needs an audience-sigstore token instead. |
LPM_GITLAB_OIDC_TOKEN | Legacy GitLab alias. Accepted on the registry-exchange and provenance surfaces for back-compat. New setups should mint LPM_OIDC_TOKEN (registry exchange) or SIGSTORE_ID_TOKEN (provenance). |
SIGSTORE_ID_TOKEN | GitLab CI OIDC token with audience sigstore, minted via the id_tokens block. Drives lpm publish --provenance on GitLab. Not used by registry-exchange surfaces (wrong audience). |
LPM_VAULT_ID | Override the project's resolved vault-id when running lpm env operations. Useful in CI workflows that target a vault other than what the checked-out project's lpm.json > "vault" field would resolve to (e.g., the lpm ci setup github-actions snippet sets this on the lpm env pull --oidc step). Falls back to the project's vault-id when unset. See Secrets vault — Per-project identity. |
| Variable | Effect |
|---|
LPM_HOME | Override the LPM root (~/.lpm by default). Moves the store, cache, global installs, and config. Useful for hermetic CI runs. |
| Variable | Effect |
|---|
LPM_LINKER | node_modules layout for installs in this process. Accepts isolated (pnpm-style strict-deps) or hoisted (npm-style flat). Useful for forcing a specific layout in CI without editing config or per-invocation flags; setting it also opts out of default peer-conflict auto-isolation. Equivalent to --linker=<value>. Sits below --linker and ~/.lpm/config.toml > linker in the precedence chain, and above package.json > lpm > linker. Unknown values fail loudly at install time — there is no silent fallback, even on the up-to-date cache fast path. Empty-string (LPM_LINKER="") is treated the same as unset, so an unset NAME || NAME="" automation pattern doesn't accidentally pin a layout. |
LPM_AUDIT_AFTER_INSTALL | Toggle audit after install for this process. Accepts 1 / true / yes / on (enable) and 0 / false / no / off (disable). Anything else falls through to ~/.lpm/config.toml > audit-after-install. Per-invocation overrides: --audit-after-install / --no-audit-after-install. Findings are informational — they never fail the install. |
LPM_CONCURRENT_DOWNLOADS | Cap the number of concurrent tarball downloads during install. Integer in 1..=256; default 24. Out-of-range or unparseable values warn on stderr and fall back to the default — set this only when you have a measured reason. |
LPM_NO_AUTO_INSTALL | Set to true to disable automatic managed-runtime installation when lpm.json > runtime.node or lpm.json > runtime.bun is missing locally. |
LPM_FORCE_TOOL_INSTALL | Set to 1 to force re-download a built-in tool even if the binary already exists in the cache. Useful when a downloaded binary has been corrupted. |
LPM_ALLOW_UNVERIFIED_PLUGINS | Set to 1 to install a plugin without checksum verification when neither a bundled nor an upstream <asset_url>.sha256 is available. The override is recorded on the plugin sidecar; reuse requires this variable on every subsequent invocation. See Built-in tools — Checksum verification. |
| Variable | Effect |
|---|
LPM_REMOTE_CACHE | 1 / true enables hosted task cache for cache-enabled tasks even when lpm.json > remoteCache.enabled is absent. 0 / false disables it for this process. |
LPM_REMOTE_CACHE_TOKEN | Bearer token for hosted cache reads and writes. Falls back to LPM_TOKEN or the token from lpm login only when the cache endpoint shares the configured registry origin. Third-party cache hosts require this variable. |
LPM_REMOTE_CACHE_URL | Override the hosted cache endpoint. Defaults to the configured registry plus /v8. HTTP is accepted only for localhost. Hosts outside the configured registry origin also require LPM_REMOTE_CACHE_SIGNATURE_KEY. |
LPM_REMOTE_CACHE_TEAM | Organization slug/team namespace. Falls back to lpm.json > remoteCache.team; unset means the authenticated personal namespace. |
LPM_REMOTE_CACHE_SIGNATURE_KEY | HMAC key for signed remote artifacts. Required when lpm.json > remoteCache.signature is true or the cache endpoint is outside the configured registry origin. |
LPM_REMOTE_CACHE_READ_ONLY | 1 / true reads hosted artifacts but skips uploads for this process. |
The Layer 5 LLM advisor persists verdicts at $LPM_HOME/cache/l4-verdicts.json so repeat installs of the same (name, version) skip the advisor round-trip.
| Variable | Effect |
|---|
LPM_L4_CACHE | Set to 0 to disable the verdict cache entirely (lookups miss, inserts are dropped). Default: enabled. Useful for measurement runs that need the cold-cache round-trip cost. |
LPM_L4_CACHE_PATH | Override the cache file location. Defaults to $LPM_HOME/cache/l4-verdicts.json. |
LPM_L4_CACHE_TTL_SECS | Override the verdict TTL in seconds. Default: 30 days. Expired entries are re-classified on next encounter. |
| Variable | Effect |
|---|
LPM_TUNNEL_RELAY | Override the tunnel relay WebSocket URL (default: wss://relay.lpm.fyi/connect). Useful for local development against a custom worker, staging, or future regional endpoints. Whitespace / empty values fall through. The TLS certificate is pinned per host under ~/.lpm/relay-pins/<host> — switching relays starts a fresh TOFU pin for that host. Persistent equivalent: tunnel.relay-url in ~/.lpm/config.toml. |
| Variable | Effect |
|---|
LPM_RESOLVER | pubgrub opts out of the default greedy-fusion resolver and uses the legacy PubGrub-with-split-retry resolver. Both speak npm-compatible semver. |
LPM_GREEDY_FUSION | 0 disables the fused dispatcher and falls back to the walker-arm orchestration for debugging. |
LPM_WALKER | Walker-dispatch picker. Diagnostic. |
LPM_NPM_FANOUT | Cap concurrent npm metadata fetches in the resolver. |
LPM_NPM_ROUTE | direct or proxy. Debug-only override of the npm package routing decision (default routes @lpm.dev/* through the LPM worker, everything else direct to registry.npmjs.org). Not a stable user knob. |
These exist for benchmarking and debugging. Don't depend on them in production.
| Variable | Effect |
|---|
LPM_HTTP | h1-pool forces an HTTP/1 connection pool instead of the default HTTP/2 path. |
LPM_STREAM_FETCH | Streaming-fetch mode toggle for the install pipeline. |
LPM_SERIAL_LINK | Disable parallel linking — useful for reproducing race conditions. |
LPM_MAX_BLOCKING_THREADS | Cap the tokio blocking-pool size. A/B benching hook for the install hot path. |
LPM_DEEP_FOLLOWUP | Resolver follow-up depth knob. |
| Variable | Effect |
|---|
LPM_FORCE_FILE_AUTH | Disable the OS keychain for token storage and force the encrypted-file fallback. Used by the test suite; also useful in sandboxed environments where the keychain isn't reachable. |
LPM_FORCE_FILE_VAULT | In debug/test builds, bypass native vault-key storage and force the encrypted-file fallback under ~/.lpm/vaults/ with ~/.lpm/.vault-fallback-key. Release builds ignore this override and use the platform default. See Secrets vault — Local storage. |
LPM_TEST_* | Reserved for the test suite; not user-facing. |
For settings that have both a CLI flag and an env var (--token / LPM_TOKEN, --registry / LPM_REGISTRY_URL, --linker / LPM_LINKER), the CLI flag wins.