Environment Variables

Set these before starting the backend (scripts/run-backend.sh) or export them in your shell/Compose/Helm values. Most have working defaults for local development; production and Model Service gateway deployments typically need to set the auth and gateway groups explicitly.

Auth and security

Variable	Description	Default
PRISM_AUTH_MODE	Auth mode (local by default).	local
PRISM_ADMIN_USERNAME / PRISM_ADMIN_PASSWORD	Seed the initial admin account on first boot.	PRISM_ADMIN_USERNAME: admin PRISM_ADMIN_PASSWORD: ""
PRISM_ADMIN_AUTOSEED	Whether to auto-create the initial admin account (default on).	True
LENS_SECRET_KEY	Master key that encrypts stored external-provider secrets. When unset, Lens generates one on first start under <LENS_DATA_DIR>/credentials/master_key.json (mode 600); set it to pin the key or make the Master key page read-only.	generated and stored on first start
LENS_SECRET_KEYS_OLD	Comma-separated previous master keys used as decryption fallback after a rotation.	""
LENS_INTERNAL_AUTH_SECRET	Shared secret for internal service-to-service calls (for example agentic planning callbacks).	""
PRISM_EXPOSE_API_DOCS	Whether to expose the FastAPI /docs page.	True

Database

Variable	Description	Default
LLM_D_BENCH_DB_MODE	embedded (bundled Postgres) or external.	embedded when LLM_D_BENCH_DATABASE_URL is unset; otherwise external
LLM_D_BENCH_DATABASE_URL	Connection string when using an external database.	— (required, no default)
LLM_D_BENCH_EMBEDDED_DB_DIR / LLM_D_BENCH_EMBEDDED_DB_PASSWORD	Data directory and password for the embedded database.	LLM_D_BENCH_EMBEDDED_DB_DIR: ~/.llm-d-lens/db/data LLM_D_BENCH_EMBEDDED_DB_PASSWORD: — (required, no default)
LLM_D_BENCH_DB_BOOTSTRAP_FILE	Optional SQL/seed file applied on first bootstrap.	~/.llm-d-lens/db-bootstrap.json

Model Service gateway (shared llm-d Gateway)

Gateway Mode: the cluster installs one shared Gateway (provider-selectable at cluster creation); model services publish HTTPRoute/IPP resources against it. Lens keeps no Edge proxy or tunnel.

Variable	Description	Default
LENS_MODEL_GATEWAY_PUBLIC_URL	A single public URL callers use for every cluster's Gateway (overrides the per-cluster URL).	""
LENS_PUBLIC_HOST	Hostname/IP external clients use to reach the Lens host; combined with each cluster's exposed port for the Gateway URL. Defaults to the request host.	""
LENS_GATEWAY_SERVICE_TYPE	Sets the Gateway data-plane Service type for clusters without a LoadBalancer (e.g. local kind). LoadBalancer, NodePort, or ClusterIP; unset keeps the provider default. Rendered through the provider's own mechanism: an EnvoyProxy for Envoy AI Gateway, a ConfigMap infrastructure.parametersRef for Istio.	unset
LENS_NODE_SYSCTL_IMAGE	Image the node-sysctl DaemonSet runs to set fs.inotify.max_user_instances on every node (needs sh/nsenter/sysctl); override when a cluster cannot pull the default.	busybox:1.36
LENS_MODEL_HEALTH_INTERVAL_SECONDS	How often published providers are health-checked (each run re-probes HTTPRoute / InferencePool / EPP / model server).	10
LENS_MODEL_RECONCILE_INTERVAL_SECONDS	How often the shared Gateway and model routes are reconciled automatically.	300
LENS_GATEWAY_EXPOSURE_INTERVAL_SECONDS	How often Lens re-establishes the public 0.0.0.0 tunnel for each cluster's exposed Gateway port.	60
LENS_GATEWAY_USAGE_INTERVAL_SECONDS	How often Lens syncs llm-d EPP token counters from each cluster's Prometheus into the usage ledger. Set 0 to disable.	60
LENS_WELCOME_CHECK_INTERVAL_SECONDS	How often Lens refreshes and stores the Welcome page issue snapshot. Set 0 to disable the background check.	60
LENS_MODEL_GATEWAY_AUTHZ_HOST	Fallback Lens ext_authz address when a cluster leaves its per-cluster Lens authz address unset. Prefer the per-cluster value (create/edit cluster form → GET /api/cluster/lens-hosts). When set, the Gateway injects the caller identity (x-llm-d-inference-fairness-id) for per-user usage.	(unset)
LENS_MODEL_GATEWAY_AUTHZ_PORT	Port of the Lens ext_authz backend used by the Gateway.	8081

The Inference Payload Processor's Helm chart and version are not environment-configurable — they're fixed constants in llm_d_lens/versions/__init__.py (oci://ghcr.io/llm-d/charts/payload-processor) and the pinned version in llm_d_lens/versions/llm_d_stack.yaml.

Storage and cache paths

Variable	Description	Default
MODEL_CACHE_DIR	Where downloaded model weights are cached per cluster.	~/.llm-d-bench/model-cache (legacy import fallback)
STORAGE_VOLUME_DIR	Root for managed storage volumes.	~/.cache/llm-d-bench/storage (legacy import fallback)
AI_PROVIDER_DIR	Where external-provider configuration is persisted.	~/.cache/llm-d-bench/ai-providers (legacy import fallback)
LENS_RUNTIME_DIR / LENS_SCRATCH_DIR	Runtime/scratch directories for backend-managed processes (port-forwards, temp files).	LENS_RUNTIME_DIR: $XDG_RUNTIME_DIR/lens if XDG_RUNTIME_DIR is set; otherwise ~/.cache/lens/tmp/runtime LENS_SCRATCH_DIR: ~/.cache/lens/tmp
HF_TOKEN	Hugging Face token used to download gated models.	— (required, no default)

Evaluation, simulation and agentic planning

Variable	Description	Default
LLM_D_BENCH_EVALUATE_STORE	Root directory for evaluation task artifacts.	~/.llm_d_lens/run_store/evaluate (legacy import fallback)
CONFIGURATION_ARTIFACT_DIR / CONFIGURATION_OUTPUT_DIR	Where rendered evaluation configurations are written.	CONFIGURATION_ARTIFACT_DIR: ~/.cache/llm-d-bench/configurations/.artifacts (legacy import fallback) CONFIGURATION_OUTPUT_DIR: ~/.cache/llm-d-bench/configurations (legacy import fallback)
SIMULATION_TASK_ROOT	Root directory for simulation task state and traces.	~/.cache/llm-d-bench/simulations (legacy import fallback)
SIMULATION_MAX_CONCURRENT_DOWNLOADS	Caps concurrent trace/asset downloads during simulation.	1
AGENTIC_OPENAI_BASE_URL / AGENTIC_OPENAI_API_KEY / AGENTIC_OPENAI_MODEL / AGENTIC_OPENAI_TIMEOUT_SECONDS	Default chat model used by agentic deployment planning when no per-request provider is chosen.	AGENTIC_OPENAI_BASE_URL: "" AGENTIC_OPENAI_API_KEY: "" AGENTIC_OPENAI_MODEL: "" AGENTIC_OPENAI_TIMEOUT_SECONDS: 30
LLM_D_BENCHMARK_ROOT / LLM_D_BENCH_SPECIFICATION_FILE	Location of the llm-d-benchmark checkout and its specification file used to drive benchmark runs.	LLM_D_BENCHMARK_ROOT: "" LLM_D_BENCH_SPECIFICATION_FILE: guides/optimized-baseline for baseline/default runs; otherwise computed from the selected guide when unset

Kubernetes and networking

Variable	Description	Default
TARGET_NODE	Optional node constraint for scripts/lens-local.sh check/start/restart; overridden by --target-node. Exported to backend/Node as PRISM_K8S_TARGET_NODE.	unset; falls back to PRISM_K8S_TARGET_NODE
KUBECONFIG	Fallback kubeconfig when a cluster-specific one isn't registered. The local launcher accepts --kubeconfig FILE as an override.	Kubernetes configuration lookup, normally $HOME/.kube/config
PRISM_GPU_PCI_ALLOWLIST	Optional explicit comma-separated PCI restriction. The local launcher preserves it; hardware discovery remains in the backend.	unset
PRISM_KUBERNETES_BACKEND / PRISM_KUBERNETES_READ_BACKEND	Selects which Kubernetes client implementation serves writes/reads.	PRISM_KUBERNETES_BACKEND: sdk PRISM_KUBERNETES_READ_BACKEND: sdk
LLM_D_BENCH_DEPLOY_RUNTIME_ENABLED	Enables local deployment resource creation. Set to false for a read-only process.	true
LLM_D_ROOT	Local llm-d checkout containing guides/.	$LENS_CACHE_DIR/llm-d in local development
LLM_D_BENCH_KUBECTL_PATH / LLM_D_BENCH_HELM_PATH / LLM_D_BENCH_DOCKER_PATH	Optional explicit executable paths for deployment tooling.	discovered from PATH
LLM_D_BENCH_NAMESPACE_PREFIX	Prefix for namespaces created by the deployment runtime.	llmd-
LLM_D_BENCH_READINESS_TIMEOUT_SECONDS / LLM_D_BENCH_KUBECTL_TIMEOUT_SECONDS	Deployment readiness and command timeouts.	900 / 300
LLM_D_BENCH_RETAIN_NAMESPACE_ON_FAILURE	Retains failed deployment namespaces for troubleshooting.	true
PRISM_MODEL_API_PUBLIC_HOST	Optional externally reachable host for Model API port-forward listeners.	"" (localhost only)
HTTP_PROXY / HTTPS_PROXY / NO_PROXY	Standard proxy variables; the backend always adds each cluster's own API server host to NO_PROXY regardless of what's inherited, to avoid tunneling cluster-local traffic through an outbound proxy.	HTTP_PROXY: "" HTTPS_PROXY: "" NO_PROXY: ""
LENS_TRUSTED_AI_PROVIDER_PROXY	Optional exact HTTPS proxy URL for external AI providers. When unset, an inherited HTTPS_PROXY/ALL_PROXY is trusted by default so the original hostname and SNI are sent through it. A mismatched value keeps application-side IP pinning.	unset

The local launcher does not load a target-node configuration file or inject LLM_D_BENCH_* defaults. These deployment defaults belong to the backend; explicit environment overrides still work. See CLI Reference for target-node preflight and argument precedence.

Kubernetes backend selection

Configuration	Recognized reads	Supported writes
Neither backend variable set	SDK	SDK
PRISM_KUBERNETES_BACKEND=sdk	SDK	SDK
PRISM_KUBERNETES_BACKEND=cli	CLI	CLI
Only PRISM_KUBERNETES_READ_BACKEND=sdk	SDK	CLI
Only PRISM_KUBERNETES_READ_BACKEND=cli	CLI	CLI

The full backend variable overrides the legacy read-only variable. Invalid values fail. Restart the backend after changing its environment. Dependencies come from apps/backend/pyproject.toml; from the repository root install them in the backend environment with pip install -e apps/backend.

Unsupported command forms choose CLI before execution; an SDK request failure never retries through CLI. Keep kubectl installed: client-side apply, Helm/Kustomize, exec, port-forward, streaming/workload-selector logs, unsupported rollout/wait and advanced flags retain CLI behavior. SDK mode does not eliminate those tools or guarantee remote API reachability.

Grep os.environ.get(...)/os.getenv(...) under apps/backend/src/llm_d_lens/ for the full, authoritative list — this page covers the ones you're most likely to need to set.