Skip to main content

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​

VariableUse
VERDICTAN_API_URLControl-plane origin. Overrides the connection file and saved session URL; --api-url takes priority.
VERDICTAN_API_TOKENBearer credential. Overrides the connection file and saved terminal session. A gateway process uses its runtime credential here.
VERDICTAN_CONFIGCLI connection-file path; --config takes priority.
VERDICTAN_LANGEnglish-only output selection. A non-English value warns; --lang takes priority.
VERDICTAN_REGIONGateway 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​

VariableUse
VERDICTAN_RUNTIME_REGISTRATION_IDRuntime registration identity when the command does not supply it.
VERDICTAN_GATEWAY_IDGateway label override; connected configuration can supply the control-plane label.
VERDICTAN_AGENT_IDExact agent binding.
VERDICTAN_AGENT_NAMEAgent name or ID to resolve when the command does not supply an agent.
VERDICTAN_GATEWAY_MAX_CONCURRENCYUpstream concurrency when the command does not set it.
VERDICTAN_UPSTREAM_URLFixed upstream base URL when --upstream is absent.
VERDICTAN_UPSTREAM_API_KEYFixed-upstream credential.
VERDICTAN_UPSTREAM_API_KEY_HEADERCredential header; defaults to Authorization.
VERDICTAN_UPSTREAM_API_KEY_PREFIXCredential prefix; defaults to Bearer , including the trailing space.
VERDICTAN_GATEWAY_EXECUTION_TARGETSHost-authorized execution families, comma-separated, or all. Without authorization, execution targets return 503 connected_gateway_required. See Execution targets.
VERDICTAN_RELAY_URLExplicit relay URL. Include https:// for an encrypted remote connection.
VERDICTAN_RELAY_MAX_PROTOCOL_VERSIONMaximum offered relay protocol; default 2.
VERDICTAN_RELAY_MAX_CONCURRENT_REQUESTSPer-session protocol-v2 concurrency; default 128.
VERDICTAN_HEALTH_PROBE_INTERVAL_SECSOverrides 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​

VariableUse and default
VERDICTAN_DATA_DIRBase 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_DIROverrides the durable event-buffer directory only. With multi-runtime supervision, runtime-specific subdirectories isolate buffers.
VERDICTAN_EVENT_WAL_MAX_BYTESDurable event-buffer byte limit; default 1 GiB.
VERDICTAN_EVENT_WAL_FULL_POLICYrefuse by default. drop_oldest_non_usage can remove older decision and Trail events while retaining usage records.
VERDICTAN_EVENT_WAL_MAX_AGE_SECONDSDecision and Trail event age limit with drop_oldest_non_usage. Usage records do not expire through this setting.
VERDICTAN_NATIVE_DIROptional 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_MSOCR 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.

VariableUse
VERDICTAN_LLM_CACHE_ENABLEDEnables the cache when true; default enabled.
VERDICTAN_LLM_CACHE_TTL_SECSEntry lifetime; default 14 days.
VERDICTAN_LLM_CACHE_BUSTERCache namespace/version input. Change it to prevent reuse of earlier entries.
VERDICTAN_LLM_CACHE_DIRFilesystem cache directory.
VERDICTAN_LLM_CACHE_MAX_BYTESLocal cache byte limit.
VERDICTAN_LLM_CACHE_WARMUP_ENABLEDFilesystem warmup selection.
VERDICTAN_LLM_CACHE_CLEARDeletes cache contents when the backend opens. Keep it off when entries must survive startup.
VERDICTAN_LLM_CACHE_REDIS_URLRedis or Valkey URL for shared cache and configured distributed consumers.
VERDICTAN_LLM_CACHE_REDIS_KEY_PREFIXRedis/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.

VariableUse
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKENAmbient SigV4 credentials for Bedrock and SageMaker when explicit credential variable names are absent; otherwise the AWS credential chain applies.
AWS_REGION, AWS_DEFAULT_REGIONAmbient SDK region settings. They do not replace the required declarative aws_region for provider routing.
GOOGLE_VERTEX_ACCESS_TOKENVertex access-token override.
GOOGLE_APPLICATION_CREDENTIALSGoogle service-account JSON path.
GCE_METADATA_ROOTGoogle metadata-server override.
WATSONX_ACCESS_TOKENwatsonx bearer override. It does not replace declarative API-version and project/space fields.
VERDICTAN_GITHUB_MODELS_API_VERSIONGitHub Models API-version override.
LLAMA_BASE_URLLocal llama.cpp or Ollama endpoint for applicable local routing.
VERDICTAN_NLI_ENDPOINT, VERDICTAN_NLI_TOKENOptional quality-scoring NLI service and credential.
VERDICTAN_CITATION_URL_LOOKUPLive citation URL-lookup selection. See Citation verifier.
HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, NO_PROXYProxy settings for supported HTTP paths, including optional-model downloads. Check the provider guide for its transport.

Child-process limits​

VariableDefaultLimit
VERDICTAN_CHILD_PROCESS_CAPACITY16Maximum 64 concurrent bounded child processes
VERDICTAN_CHILD_BLOCKING_CAPACITY4Maximum 16 blocking child-helper tasks
VERDICTAN_CHILD_STDOUT_MAX_BYTES8388608Per-child standard-output bytes
VERDICTAN_CHILD_STDERR_MAX_BYTES8388608Per-child standard-error bytes
VERDICTAN_CHILD_TOTAL_MAX_BYTES16777216Combined output; must be between the larger stream limit and their sum
VERDICTAN_CHILD_TIMEOUT_SECONDS30Absolute child timeout; hard maximum 300 seconds

Execution-target configuration can impose additional constraints. See Execution targets.

Logs and OpenTelemetry​

VariableUse
VERDICTAN_LOGLocal diagnostic filter; default info, or warn for the minimal profile.
VERDICTAN_LOG_FORMATjson selects structured local logs; otherwise human-readable output.
VERDICTAN_ENVRuntime and telemetry environment label; development/test values also affect automatic cache selection.
OTEL_SDK_DISABLEDtrue, 1, or yes disables telemetry export.
OTEL_EXPORTER_OTLP_ENDPOINTCommon collector base URL. No configured endpoint means no export.
OTEL_EXPORTER_OTLP_PROTOCOLgrpc by default, or http/protobuf.
OTEL_EXPORTER_OTLP_HEADERSComma-separated exporter headers; values support percent encoding.
OTEL_EXPORTER_OTLP_TIMEOUTMilliseconds; default 1000, allowed 1 through 30000.
OTEL_EXPORTER_OTLP_CERTIFICATEPEM certificate-authority file.
OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEYMatching mutual-TLS certificate and key files.
OTEL_TRACES_SAMPLERparentbased_traceidratio by default; also traceidratio, always_on, always_off, parentbased_always_on, or parentbased_always_off.
OTEL_TRACES_SAMPLER_ARGRoot trace sample ratio; default 0.1.
OTEL_TRACES_EXPORTER, OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTERnone disables export of the selected signal.
OTEL_SERVICE_NAME, OTEL_RESOURCE_ATTRIBUTESService 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​

VariableUse
VERDICTAN_DOWNLOAD_URLAlternate HTTPS release-asset base for the installer. The downloaded archive must still match its embedded checksum.
VERDICTAN_INSTALL_DIRAbsolute install directory. Defaults to ~/.local/bin on Unix and %LOCALAPPDATA%\Verdictan\bin on Windows.
VERDICTAN_NO_MODIFY_PATHAny nonempty value prevents installer changes to shell profiles or the Windows user PATH.
XDG_CONFIG_HOMEUnix installer shell-environment file location; defaults to ~/.config/verdictan/env.
VERDICTAN_UPDATE_MANIFEST_URLSelects the signed-manifest update path for verdictan-update.
VERDICTAN_UPDATE_PUBLIC_KEYBase64 Ed25519 public key for that manifest.
VERDICTAN_UPDATE_ALLOW_DOWNGRADE1, 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​