CLI and gateway environment variables
Set variables in the environment of the process that reads them. A value exported in another terminal is not visible to an existing gateway. Services and containers need their own environment. Start with gateway run for a foreground process or gateway install for a service.
This reference covers customer configuration. Desktop supervisors supply their private account pipes and managed child credentials through the supervision and ACP protocols.
CLI connection
| Variable | Use |
|---|---|
VERDICTAN_API_URL | Control-plane origin. Overrides the connection file and saved session URL; --api-url takes priority. |
VERDICTAN_API_TOKEN | Bearer credential. Overrides the connection file and saved terminal session. A gateway process uses its runtime credential here. |
VERDICTAN_CONFIG | CLI connection-file path; --config takes priority. |
VERDICTAN_LANG | English-only output selection. A non-English value warns; --lang takes priority. |
VERDICTAN_REGION | Gateway deployment and telemetry region label. It is not a CLI region fallback. |
See CLI scripting for precedence and profiles for stored region defaults.
Gateway connection and routing
| Variable | Use |
|---|---|
VERDICTAN_RUNTIME_REGISTRATION_ID | Runtime registration identity when the command does not supply it. |
VERDICTAN_GATEWAY_ID | Gateway label override; connected configuration can supply the control-plane label. |
VERDICTAN_AGENT_ID | Exact agent binding. |
VERDICTAN_AGENT_NAME | Agent name or ID to resolve when the command does not supply an agent. |
VERDICTAN_GATEWAY_MAX_CONCURRENCY | Upstream concurrency when the command does not set it. |
VERDICTAN_UPSTREAM_URL | Fixed upstream base URL when --upstream is absent. |
VERDICTAN_UPSTREAM_API_KEY | Fixed-upstream credential. |
VERDICTAN_UPSTREAM_API_KEY_HEADER | Credential header; defaults to Authorization. |
VERDICTAN_UPSTREAM_API_KEY_PREFIX | Credential prefix; defaults to Bearer , including the trailing space. |
VERDICTAN_GATEWAY_EXECUTION_TARGETS | Host-authorized execution families, comma-separated, or all. Without authorization, execution targets return 503 connected_gateway_required. See Execution targets. |
VERDICTAN_RELAY_URL | Explicit relay URL. Include https:// for an encrypted remote connection. |
VERDICTAN_RELAY_MAX_PROTOCOL_VERSION | Maximum offered relay protocol; default 2. |
VERDICTAN_RELAY_MAX_CONCURRENT_REQUESTS | Per-session protocol-v2 concurrency; default 128. |
VERDICTAN_HEALTH_PROBE_INTERVAL_SECS | Overrides provider health intervals, clamped to 10 through 300 seconds. |
See Central agent URL for relay selection and limits. Client-IP trust uses policy fields such as ip_allowlist.trusted_proxy_cidrs; gateway proxy trust is not configured with an environment variable.
Data and event storage
| Variable | Use and default |
|---|---|
VERDICTAN_DATA_DIR | Base for gateway data and registration.json. Auto-registration uses a system temporary directory when unset; optional models and the sealed MCP outbox instead default to ~/.verdictan/data. Set a persistent path for persistent identity and data. |
VERDICTAN_EVENT_WAL_DATA_DIR | Overrides the durable event-buffer directory only. With multi-runtime supervision, runtime-specific subdirectories isolate buffers. |
VERDICTAN_EVENT_WAL_MAX_BYTES | Durable event-buffer byte limit; default 1 GiB. |
VERDICTAN_EVENT_WAL_FULL_POLICY | refuse by default. drop_oldest_non_usage can remove older decision and Trail events while retaining usage records. |
VERDICTAN_EVENT_WAL_MAX_AGE_SECONDS | Decision and Trail event age limit with drop_oldest_non_usage. Usage records do not expire through this setting. |
VERDICTAN_NATIVE_DIR | Optional absolute, prepared read-only native-module directory on Unix. Files and parent directories must have trusted ownership and no group or other write access. Otherwise, native modules are extracted under ~/.verdictan/native. Windows does not support this override. |
VERDICTAN_OCR_TIMEOUT_MS | OCR time limit per image. Default 10000; maximum 600000 milliseconds. An image that exceeds the limit stays unread. |
Install optional artifacts with verdictan models. The gateway does not download them. Use the same data directory for installation and execution. Gateway event storage explains buffer behavior and recovery.
Response cache and shared state
Set VERDICTAN_LLM_CACHE_BACKEND explicitly in production: memory, filesystem, redis, valkey, s3, gcs, or qdrant. An unset value or auto selects memory in a development or test environment and stops startup otherwise. Desktop-supervised gateways select disabled memory caching and remove inherited cache settings.
| Variable | Use |
|---|---|
VERDICTAN_LLM_CACHE_ENABLED | Enables the cache when true; default enabled. |
VERDICTAN_LLM_CACHE_TTL_SECS | Entry lifetime; default 14 days. |
VERDICTAN_LLM_CACHE_BUSTER | Cache namespace/version input. Change it to prevent reuse of earlier entries. |
VERDICTAN_LLM_CACHE_DIR | Filesystem cache directory. |
VERDICTAN_LLM_CACHE_MAX_BYTES | Local cache byte limit. |
VERDICTAN_LLM_CACHE_WARMUP_ENABLED | Filesystem warmup selection. |
VERDICTAN_LLM_CACHE_CLEAR | Deletes cache contents when the backend opens. Keep it off when entries must survive startup. |
VERDICTAN_LLM_CACHE_REDIS_URL | Redis or Valkey URL for shared cache and configured distributed consumers. |
VERDICTAN_LLM_CACHE_REDIS_KEY_PREFIX | Redis/Valkey cache key prefix. |
The cache backend table lists the complete VERDICTAN_LLM_CACHE_S3_*, VERDICTAN_LLM_CACHE_GCS_*, and VERDICTAN_LLM_CACHE_QDRANT_* variables, including required bucket, region, credential, endpoint, and collection inputs. GCS uses interoperability access keys for this backend.
Distributed rate limits and session counters need the shared backend specified by the policy. A missing required URL stops startup. Runtime backend loss fails readiness; admission behavior depends on the consumer and its failure mode. See Rate limits before you select fail-open behavior. A separate cache command process cannot inspect the memory cache of a running gateway.
Provider and policy-service credentials
Provider keys use the variable named by providers.targets[].secret_key_ref.env; the name is chosen in your configuration. A variable such as OPENAI_API_KEY does not configure a target by itself. Connected local recovery can use matching Verdictan-prefixed provider variables. See Environment variable use for env, hosted secret records, and surfaces that accept each form.
| Variable | Use |
|---|---|
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN | Ambient SigV4 credentials for Bedrock and SageMaker when explicit credential variable names are absent; otherwise the AWS credential chain applies. |
AWS_REGION, AWS_DEFAULT_REGION | Ambient SDK region settings. They do not replace the required declarative aws_region for provider routing. |
GOOGLE_VERTEX_ACCESS_TOKEN | Vertex access-token override. |
GOOGLE_APPLICATION_CREDENTIALS | Google service-account JSON path. |
GCE_METADATA_ROOT | Google metadata-server override. |
WATSONX_ACCESS_TOKEN | watsonx bearer override. It does not replace declarative API-version and project/space fields. |
VERDICTAN_GITHUB_MODELS_API_VERSION | GitHub Models API-version override. |
LLAMA_BASE_URL | Local llama.cpp or Ollama endpoint for applicable local routing. |
VERDICTAN_NLI_ENDPOINT, VERDICTAN_NLI_TOKEN | Optional quality-scoring NLI service and credential. |
VERDICTAN_CITATION_URL_LOOKUP | Live citation URL-lookup selection. See Citation verifier. |
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXY | Proxy settings for supported HTTP paths, including optional-model downloads. Check the provider guide for its transport. |
Child-process limits
| Variable | Default | Limit |
|---|---|---|
VERDICTAN_CHILD_PROCESS_CAPACITY | 16 | Maximum 64 concurrent bounded child processes |
VERDICTAN_CHILD_BLOCKING_CAPACITY | 4 | Maximum 16 blocking child-helper tasks |
VERDICTAN_CHILD_STDOUT_MAX_BYTES | 8388608 | Per-child standard-output bytes |
VERDICTAN_CHILD_STDERR_MAX_BYTES | 8388608 | Per-child standard-error bytes |
VERDICTAN_CHILD_TOTAL_MAX_BYTES | 16777216 | Combined output; must be between the larger stream limit and their sum |
VERDICTAN_CHILD_TIMEOUT_SECONDS | 30 | Absolute child timeout; hard maximum 300 seconds |
Execution-target configuration can impose additional constraints. See Execution targets.
Logs and OpenTelemetry
| Variable | Use |
|---|---|
VERDICTAN_LOG | Local diagnostic filter; default info, or warn for the minimal profile. |
VERDICTAN_LOG_FORMAT | json selects structured local logs; otherwise human-readable output. |
VERDICTAN_ENV | Runtime and telemetry environment label; development/test values also affect automatic cache selection. |
OTEL_SDK_DISABLED | true, 1, or yes disables telemetry export. |
OTEL_EXPORTER_OTLP_ENDPOINT | Common collector base URL. No configured endpoint means no export. |
OTEL_EXPORTER_OTLP_PROTOCOL | grpc by default, or http/protobuf. |
OTEL_EXPORTER_OTLP_HEADERS | Comma-separated exporter headers; values support percent encoding. |
OTEL_EXPORTER_OTLP_TIMEOUT | Milliseconds; default 1000, allowed 1 through 30000. |
OTEL_EXPORTER_OTLP_CERTIFICATE | PEM certificate-authority file. |
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEY | Matching mutual-TLS certificate and key files. |
OTEL_TRACES_SAMPLER | parentbased_traceidratio by default; also traceidratio, always_on, always_off, parentbased_always_on, or parentbased_always_off. |
OTEL_TRACES_SAMPLER_ARG | Root trace sample ratio; default 0.1. |
OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER | none disables export of the selected signal. |
OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTES | Service identity and supported resource attributes. |
For each of TRACES, METRICS, and LOGS, OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT, _PROTOCOL, _HEADERS, _TIMEOUT, _CERTIFICATE, _CLIENT_CERTIFICATE, and _CLIENT_KEY override the common setting. A signal-specific endpoint is the complete URL; an HTTP common endpoint receives the signal path suffix. Signal-specific headers replace common headers.
Operational export excludes customer payloads. Invalid exporter settings disable export and produce a diagnostic; collector failure does not change the command exit code. Local diagnostics use standard error and preserve command standard output. See Observability.
Installation and signed updates
| Variable | Use |
|---|---|
VERDICTAN_DOWNLOAD_URL | Alternate HTTPS release-asset base for the installer. The downloaded archive must still match its embedded checksum. |
VERDICTAN_INSTALL_DIR | Absolute install directory. Defaults to ~/.local/bin on Unix and %LOCALAPPDATA%\Verdictan\bin on Windows. |
VERDICTAN_NO_MODIFY_PATH | Any nonempty value prevents installer changes to shell profiles or the Windows user PATH. |
XDG_CONFIG_HOME | Unix installer shell-environment file location; defaults to ~/.config/verdictan/env. |
VERDICTAN_UPDATE_MANIFEST_URL | Selects the signed-manifest update path for verdictan-update. |
VERDICTAN_UPDATE_PUBLIC_KEY | Base64 Ed25519 public key for that manifest. |
VERDICTAN_UPDATE_ALLOW_DOWNGRADE | 1, true, or yes permits an explicitly signed downgrade; default rejects it. |
Use the owning package manager to update package-managed installations. See Install the gateway for supported channels and service restrictions.
Next steps
- CLI scripting: input, output, and exit rules.
- Runtime configuration: cache and runtime fields.
- Provider configuration: targets and credential references.