Environment Variables

This page documents all environment variables that can be used to configure HolmesGPT behavior.

AI Provider Configuration

OpenAI

• OPENAI_API_KEY - API key for OpenAI models
• OPENAI_API_BASE - Custom base URL for OpenAI-compatible APIs (e.g., LiteLLM proxy, local inference servers). See OpenAI-Compatible for details.

Anthropic

• ANTHROPIC_API_KEY - API key for Anthropic Claude models

Google

• GEMINI_API_KEY - API key for Google Gemini models
• GOOGLE_API_KEY - Alternative API key for Google services

Azure AI Foundry

• AZURE_API_KEY - API key for Azure AI Foundry service
• AZURE_API_BASE - Base URL for Azure AI Foundry endpoint
• AZURE_API_VERSION - API version to use (e.g., "2024-02-15-preview")

AWS Bedrock

• AWS_ACCESS_KEY_ID - AWS access key ID
• AWS_SECRET_ACCESS_KEY - AWS secret access key
• AWS_DEFAULT_REGION - AWS region for Bedrock

Google Vertex AI

• VERTEXAI_PROJECT - Google Cloud project ID
• VERTEXAI_LOCATION - Vertex AI location (e.g., "us-central1")
• GOOGLE_APPLICATION_CREDENTIALS - Path to service account key JSON file

Robusta AI

These settings matter with the Robusta platform, except that the interactive CLI also uses ROBUSTA_API_ENDPOINT to check for the latest Holmes release. See Robusta AI for setting it up.

ROBUSTA_AI

Default: not set

Server only, when it is configured from environment variables (as with the Helm chart). true makes the Holmes server load the models the Robusta platform offers the account (Robusta AI); false keeps them out. When not set, the server loads them only when neither MODEL nor a model list is configured. The CLI never loads them.

ROBUSTA_API_ENDPOINT

Default:

US EU AP

https://api.robusta.dev

https://api.eu.robusta.dev

https://api.ap.robusta.dev

Base URL of the Robusta platform API. When Holmes connects to the platform, it fetches the data store's API key from it (/api/config/supabase-keys), and when the fetch or the login with the fetched key fails, it uses the api_key in the Robusta UI token (or STORE_API_KEY without a token) instead. Holmes also fetches the account's Robusta AI models from it, sends Robusta AI completions through it, and reaches the Robusta platform MCP server under it (unless ROBUSTA_MCP_ENDPOINT is set). The interactive CLI also checks it for the latest Holmes release, with or without the platform. Set it to your region's API, or to a self-hosted platform's API URL:

Holmes Helm ChartRobusta Helm Chart

US EU AP

additionalEnvVars:
  - name: ROBUSTA_API_ENDPOINT
    value: "https://api.robusta.dev"

additionalEnvVars:
  - name: ROBUSTA_API_ENDPOINT
    value: "https://api.eu.robusta.dev"

additionalEnvVars:
  - name: ROBUSTA_API_ENDPOINT
    value: "https://api.ap.robusta.dev"

US EU AP

holmes:
  additionalEnvVars:
    - name: ROBUSTA_API_ENDPOINT
      value: "https://api.robusta.dev"

holmes:
  additionalEnvVars:
    - name: ROBUSTA_API_ENDPOINT
      value: "https://api.eu.robusta.dev"

holmes:
  additionalEnvVars:
    - name: ROBUSTA_API_ENDPOINT
      value: "https://api.ap.robusta.dev"

ROBUSTA_UI_DOMAIN

Default:

US EU AP

https://platform.robusta.dev

https://platform.eu.robusta.dev

https://platform.ap.robusta.dev

Base URL of the Robusta UI. Holmes builds links to platform chats on it, accepts conversation links on its host, and fetches the additional system prompt for scheduled prompts from it. Set it to your region's UI, or to a self-hosted platform's UI URL:

Holmes Helm ChartRobusta Helm Chart

US EU AP

additionalEnvVars:
  - name: ROBUSTA_UI_DOMAIN
    value: "https://platform.robusta.dev"

additionalEnvVars:
  - name: ROBUSTA_UI_DOMAIN
    value: "https://platform.eu.robusta.dev"

additionalEnvVars:
  - name: ROBUSTA_UI_DOMAIN
    value: "https://platform.ap.robusta.dev"

US EU AP

holmes:
  additionalEnvVars:
    - name: ROBUSTA_UI_DOMAIN
      value: "https://platform.robusta.dev"

holmes:
  additionalEnvVars:
    - name: ROBUSTA_UI_DOMAIN
      value: "https://platform.eu.robusta.dev"

holmes:
  additionalEnvVars:
    - name: ROBUSTA_UI_DOMAIN
      value: "https://platform.ap.robusta.dev"

ROBUSTA_UI_TOKEN

Default: not set

The Robusta UI token: base64-encoded JSON carrying the account ID and the credentials and URL of the account's data store. Holmes uses it to connect to the Robusta platform. When it is not set, Holmes reads the token of the robusta_sink in the Robusta config file (ROBUSTA_CONFIG_PATH, default /etc/robusta/config/active_playbooks.yaml). Without a token, Holmes connects with ROBUSTA_ACCOUNT_ID, STORE_URL, STORE_API_KEY, STORE_EMAIL and STORE_PASSWORD when all five are set (see Robusta toolset); otherwise it does not connect to the platform and cannot use Robusta AI. A robusta_sink in the config file without a token is an error.

LLM Tool Calling Configuration

HOLMES_DISABLE_STRICT_TOOL_CALLS

Default: false

When set to true, disables strict tool calling for all models. By default, strict mode is enabled universally — HolmesGPT sets strict: true and additionalProperties: false on all tool schemas. This prevents LLMs from hallucinating parameter names or sending malformed arguments.

Tools with dynamic-key parameters (additionalProperties with a schema, e.g., filter maps) are automatically excluded from strict mode on a per-tool basis, since both OpenAI and Anthropic require additionalProperties: false on all objects in strict mode.

Example:

export HOLMES_DISABLE_STRICT_TOOL_CALLS=true

TOOL_SCHEMA_NO_PARAM_OBJECT_IF_NO_PARAMS

Default: false

When set to true, removes the parameters object from tool schemas when a tool has no parameters. This is specifically required for Google Gemini models which don't expect a parameters object for parameterless functions.

Example:

export TOOL_SCHEMA_NO_PARAM_OBJECT_IF_NO_PARAMS=true

Note: This setting is typically only needed when using Gemini models. Other providers handle empty parameter objects correctly.

LLM Rate Limits

LLM_RATE_LIMIT_MAX_WAIT_SECONDS

Default: 30

Maximum time a single LLM call may spend backing off from provider rate-limit errors (HTTP 429, Bedrock throttling), Anthropic overloaded errors (HTTP 529) and service-unavailable errors (HTTP 503, e.g. Bedrock ServiceUnavailableException) before the error is returned. HolmesGPT waits at least as long as the provider's Retry-After header asks, and otherwise backs off exponentially with jitter from 2 to 60 seconds. A backoff that would go over the budget is shortened to what is left; if the provider's Retry-After alone goes over it, the error is returned without waiting. Time spent in the requests themselves is not counted, so a call whose failing attempts are each slow takes longer than the budget overall. Only the failing LLM call is retried, so tool calls already made during an investigation are kept. Set to 0 to disable these retries.

Not retried:

• A Robusta AI account that has reached its limit, since waiting does not clear it. Other providers' quota errors look like ordinary rate limits (Gemini words its per-minute limit the same way as OpenAI's out-of-credit error), so they are retried until the budget runs out.
• Tool-output summarization by the fast model, which falls back to the unsummarized output instead.

Interrupting the CLI (Esc) stops the backoff. Server requests run until the budget is used up.

When the budget runs out the error is returned as before: rate limits as HTTP 429 from /api/chat (code 5204 in a stream), overloaded and service-unavailable errors as HTTP 500.

Conversation-history compaction may summarize in several requests; they all share one budget, and an exhausted budget is returned as the errors above.

Some providers' SDKs (OpenAI, Azure) also retry a rate limit once or twice within each attempt. That time does not count towards the budget.

Example:

export LLM_RATE_LIMIT_MAX_WAIT_SECONDS=180

Server Security

HOLMES_API_KEY

Default: not set (authentication disabled)

When set, all API requests must include this key via either:

• X-API-Key: <key> header, or
• Authorization: Bearer <key> header

Health check endpoints (/healthz, /readyz) are always exempt.

Generating a key:

# Generate a random key with 32 bytes of entropy
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Or use openssl
openssl rand -base64 32

Example:

export HOLMES_API_KEY=my-secret-key-here

Docker example:

docker run -d \
  -e HOLMES_API_KEY=your-generated-key \
  ...

HOLMES_APPROVAL_SIGNING_KEY

Default: not set (an ephemeral key is generated per process at startup)

HMAC signing key for tool-approval tokens. Holmes mints a short-lived JWT for every tool call that requires user approval and verifies the same JWT when the user approves. This prevents a client from forging an approval for a tool call Holmes never proposed.

When unset, Holmes generates a 32-byte random key at startup. Approvals still work, but in-flight approvals are invalidated on every restart — users will see "Approval token validation failed" if they approve a modal after Holmes restarted. Set this env var to keep approvals working across restarts.

Generating a key:

openssl rand -base64 32

The env var is used verbatim as the HMAC key — any string works, but use a high-entropy value like the snippet above. A short or guessable key silently weakens the signature and lets a client forge approval tokens.

Example (Kubernetes):

additionalEnvVars:
  - name: HOLMES_APPROVAL_SIGNING_KEY
    valueFrom:
      secretKeyRef:
        name: holmes-secrets
        key: approval-signing-key

Tokens expire after 30 days.

SSL/TLS

CERTIFICATE

Base64-encoded custom CA certificate for outbound HTTPS requests. When set, the certificate is appended to the default CA bundle so that HolmesGPT trusts your private CA for all connections (LLM APIs, Elasticsearch, Prometheus, etc.).

Holmes CLIHolmes Helm ChartRobusta Helm Chart

export CERTIFICATE="$(base64 -w0 /path/to/ca.crt)"

certificate: "<base64-encoded CA cert>"

holmes:
  certificate: "<base64-encoded CA cert>"

API Server HTTPS (HOLMES_SSL_*)

Serve the HolmesGPT API over HTTPS directly from the application (in-app TLS — no reverse proxy or ingress required). When both HOLMES_SSL_CERTFILE and HOLMES_SSL_KEYFILE are set, the server listens with TLS; otherwise it serves plain HTTP. If only one of the two is set, if a referenced file is missing, or if HOLMES_SSL_CA_CERTS / HOLMES_SSL_KEYFILE_PASSWORD is set without both server-side files, the server fails to start rather than silently falling back to HTTP.

Variable	Required	Description
HOLMES_SSL_CERTFILE	for HTTPS	Path to the PEM server certificate. Setting this and HOLMES_SSL_KEYFILE enables HTTPS.
HOLMES_SSL_KEYFILE	for HTTPS	Path to the PEM private key for the certificate.
HOLMES_SSL_KEYFILE_PASSWORD	optional	Password for an encrypted private key.
HOLMES_SSL_CA_CERTS	optional	Path to a CA bundle used to verify client certificates. Setting it enables mutual TLS (mTLS) — clients without a CA-signed certificate are rejected.

Holmes CLIHolmes Helm Chart

export HOLMES_SSL_CERTFILE=/path/to/tls.crt
export HOLMES_SSL_KEYFILE=/path/to/tls.key
# optional:
export HOLMES_SSL_KEYFILE_PASSWORD=changeit
export HOLMES_SSL_CA_CERTS=/path/to/ca.crt   # enables mTLS

Provide a TLS secret and enable tls (see the Kubernetes installation guide):

tls:
  enabled: true
  secretName: holmes-tls   # secret with tls.crt and tls.key
  # caCertsSecretKey: ca.crt   # optional: key in the secret, enables mTLS

Certificate rotation

The server reads the certificate once at startup and does not hot-reload it. After rotating the certificate (or its secret), restart the process/pod for the new certificate to take effect.

Proxies

Holmes sends its outbound HTTP and HTTPS traffic through a proxy when the standard proxy variables are set: LLM calls, the Robusta platform and its realtime connection, and the toolsets' HTTP calls, except the ClickHouse HTTP query path and the in-process Kubernetes client (Kubernetes API calls from the Prometheus service discovery and Holmes's own log reader), which ignore the proxy variables. The commands tools run (kubectl and other CLIs) inherit the variables too, so each follows its own proxy handling.

Variable	Description
HTTPS_PROXY	Proxy URL for https:// (and wss://) requests, e.g. http://proxy.example.com:3128.
HTTP_PROXY	Proxy URL for http:// requests.
NO_PROXY	Comma-separated hosts and domain suffixes reached directly, without the proxy.

The lowercase forms (https_proxy, http_proxy, no_proxy) work too. Add the in-cluster services Holmes queries to NO_PROXY (for example .svc,.cluster.local), or their requests go to the proxy too. The kubectl commands the toolsets run inherit these variables and honor them, so add the Kubernetes API's address as well when kubectl should reach it directly.

Holmes CLIHolmes Helm ChartRobusta Helm Chart

export HTTPS_PROXY=http://proxy.example.com:3128
export HTTP_PROXY=http://proxy.example.com:3128
export NO_PROXY=localhost,127.0.0.1,.svc,.cluster.local

additionalEnvVars:
  - name: HTTPS_PROXY
    value: "http://proxy.example.com:3128"
  - name: HTTP_PROXY
    value: "http://proxy.example.com:3128"
  - name: NO_PROXY
    value: "localhost,127.0.0.1,.svc,.cluster.local"

holmes:
  additionalEnvVars:
    - name: HTTPS_PROXY
      value: "http://proxy.example.com:3128"
    - name: HTTP_PROXY
      value: "http://proxy.example.com:3128"
    - name: NO_PROXY
      value: "localhost,127.0.0.1,.svc,.cluster.local"

The Helm chart's MCP server add-ons take their own additionalEnvVars; set the proxy variables there too for them to reach out through the proxy.

If the proxy intercepts TLS, give Holmes its CA with CERTIFICATE.

LLM Provider Hosts

The hosts Holmes connects to for each LLM provider, over HTTPS (port 443) unless the row names a host you configure, which uses that URL's scheme and port. Allow only the providers you use.

Provider	Hosts
OpenAI	api.openai.com
Anthropic	api.anthropic.com
Google Gemini	generativelanguage.googleapis.com
Google Vertex AI	<location>-aiplatform.googleapis.com (aiplatform.googleapis.com for the global location, aiplatform.<location>.rep.googleapis.com for a multi-region location such as us or eu), and oauth2.googleapis.com for service account tokens
AWS Bedrock	bedrock-runtime.<region>.amazonaws.com, and sts.<region>.amazonaws.com (or sts.amazonaws.com for the global endpoint) when Holmes assumes a role
Azure AI Foundry / Azure OpenAI	The host of AZURE_API_BASE (e.g. <resource>.services.ai.azure.com, <resource>.cognitiveservices.azure.com or <resource>.openai.azure.com), and login.microsoftonline.com with AZURE_AD_TOKEN_AUTH, workload identity or a service principal (managed identity uses the instance metadata endpoint instead)
OpenRouter	openrouter.ai
OpenAI-compatible endpoints	The host of OPENAI_API_BASE
GitHub Models	models.inference.ai.azure.com
GitHub Copilot	The API host GitHub returns with the Copilot token (under *.githubcopilot.com; see GitHub's Copilot allowlist reference), and github.com and api.github.com for the device login and token exchange
Baseten	inference.baseten.co
Ollama	The host of OLLAMA_API_BASE
Robusta AI	The host of ROBUSTA_API_ENDPOINT, and the data store host (the store URL in your ROBUSTA_UI_TOKEN, the Robusta config file's token or STORE_URL) for the session token and realtime connection. See the platform allowlist

With every provider, LiteLLM downloads its model catalog from raw.githubusercontent.com at startup and on each refresh (see LITELLM_COST_MAP_REFRESH_INTERVAL_SECONDS); allow it or point LITELLM_MODEL_COST_MAP_URL at a mirror. It also fetches an Anthropic beta-headers file from the same host and falls back to a bundled copy when that fails, so a mirror for the cost map alone does not remove all traffic to it. Set LITELLM_LOCAL_MODEL_COST_MAP=True to skip the catalog download, refreshes included, and LITELLM_LOCAL_ANTHROPIC_BETA_HEADERS=True to skip the beta-headers download; both use the bundled copies.

Tool Result Size Limits

These variables control how HolmesGPT handles large tool responses that exceed the LLM context window.

When a tool returns more data than the context window can hold, Holmes can either save the result to disk (so the LLM can access it via cat, grep, etc.) or drop the data with an error asking the LLM to narrow its query.

HOLMES_TOOL_RESULT_STORAGE_ENABLED

Default: true

Controls whether large tool results are saved to the filesystem. When enabled, oversized results are written to a temp directory and the LLM receives a file path it can read with bash commands. When disabled, oversized results are dropped and the LLM is asked to retry with a narrower query.

Example:

# Disable filesystem storage for large results
export HOLMES_TOOL_RESULT_STORAGE_ENABLED=false

HOLMES_TOOL_RESULT_STORAGE_PATH

Default: System temp directory + /.holmes (e.g., /tmp/.holmes)

Directory where large tool results are saved. Each chat session creates a subdirectory that is automatically cleaned up when the session ends.

Example:

export HOLMES_TOOL_RESULT_STORAGE_PATH="/var/holmes/tool_results"

TOOL_MAX_ALLOCATED_CONTEXT_WINDOW_PCT

Default: 15

Maximum percentage of the LLM context window that a single tool response can use. If a tool result exceeds this limit, it triggers the large-result handling (filesystem storage or truncation). Set to 0 or a value above 100 to disable percentage-based limiting.

Example:

# Allow each tool response to use up to 25% of context window
export TOOL_MAX_ALLOCATED_CONTEXT_WINDOW_PCT=25

TOOL_MAX_ALLOCATED_CONTEXT_WINDOW_TOKENS

Default: 25000

Absolute maximum tokens for a single tool response, regardless of context window size. The effective limit is the minimum of this value and the percentage-based limit above.

Example:

# Raise the absolute cap to 50,000 tokens
export TOOL_MAX_ALLOCATED_CONTEXT_WINDOW_TOKENS=50000

Tool Subprocess Memory Limit

TOOL_MEMORY_LIMIT_MB

Default: 800 on x86_64, 1500 on ARM / aarch64

Per-subprocess virtual-memory cap (in MB) applied to every tool command Holmes runs. Implemented by prefixing each command with ulimit -v <value × 1024>. When a command exceeds the cap, the kernel kills it (exit 137) and Holmes prefixes the output with an [OOM] hint instructing the LLM to retry with a narrower query.

The cap limits virtual address space, not resident memory — Go binaries like kubectl can reserve hundreds of MB at startup, so set this too low and you will break commands that would otherwise use little RAM. On Kubernetes, keep this comfortably below the pod's resources.limits.memory. On macOS the cap is silently ignored (BSD kernel does not enforce ulimit -v).

See Tool Execution Safety for the full mechanism, implications, and tuning guidance.

Example:

export TOOL_MEMORY_LIMIT_MB=2000

Holmes Logs in the Robusta UI

The Robusta UI shows Holmes's own pod logs. The whole result is limited to REMOTE_TOOL_RESULT_MAX_BYTES (default 1 MB) after JSON encoding; when the logs are longer, the newest lines are kept.

HOLMES_LOGS_DEFAULT_TAIL_LINES

Default: 500

Lines per container that the UI gets when it does not ask for a number.

HOLMES_LOGS_MAX_TAIL_LINES

Default: 5000

The largest number of lines per container that a request can ask for.

Conversation Worker Executors

The conversation runtime (Robusta platform deployments) runs each conversation on a named executor. Conversations.executor names it: manual for live user asks (chat, follow-ups, a single "Investigate now") and auto for background work (auto-triage, "Add to queue" / bulk investigations, triggered workflows). Executors are created on demand and sized from the account setting conversation_executors.<name> (Settings → LLMs sets manual, Settings → Triage sets auto; applied live, no restart), falling back to the built-in default (manual=10, auto=1). CONVERSATION_WORKER_MAX_CONCURRENT (default 5) only sizes an executor whose name has no built-in default.

Upgrade note. Before executors existed, one shared pool of CONVERSATION_WORKER_MAX_CONCURRENT (5) ran everything. With the defaults above an agent now runs up to 11 conversations at once (10 manual + 1 auto), and CONVERSATION_WORKER_MAX_CONCURRENT no longer sizes those two executors. Deployments that tuned it should set the concurrency in Settings instead.

HolmesGPT Configuration

MODEL_LIST_FILE_LOCATION

Path to a YAML file that defines named model configurations. When set, you can reference models by name using --model=<name> in the CLI or the model parameter in the HTTP API, instead of specifying the full model identifier and credentials each time.

If unset, HolmesGPT looks for the model list file in this order:

1. /etc/holmes/config/model_list.yaml (server / Helm default)
2. ~/.holmes/model_list.yaml (CLI default)

Example:

export MODEL_LIST_FILE_LOCATION="/path/to/model_list.yaml"

See Using Multiple Providers for the model list file format and usage.

LITELLM_MODEL_COST_MAP_URL

Overrides the URL LiteLLM fetches the model catalog (model_prices_and_context_window.json) from. LiteLLM uses that catalog to know each model's context window, max output tokens, and pricing. By default LiteLLM pulls it from raw.githubusercontent.com, which is unreachable from networks that block GitHub egress.

Robusta hosts a mirror of the same file in each region. Pick the URL matching your Robusta region:

US EU AP

https://api.robusta.dev/litellm/model_prices_and_context_window.json

https://api.eu.robusta.dev/litellm/model_prices_and_context_window.json

https://api.ap.robusta.dev/litellm/model_prices_and_context_window.json

The mirror is cached and falls back to its last-known-good copy if the upstream is temporarily unreachable, so pointing at it gives the same freshness as the default URL without requiring egress to raw.githubusercontent.com.

Helm example:

US EU AP

additionalEnvVars:
  - name: LITELLM_MODEL_COST_MAP_URL
    value: https://api.robusta.dev/litellm/model_prices_and_context_window.json

additionalEnvVars:
  - name: LITELLM_MODEL_COST_MAP_URL
    value: https://api.eu.robusta.dev/litellm/model_prices_and_context_window.json

additionalEnvVars:
  - name: LITELLM_MODEL_COST_MAP_URL
    value: https://api.ap.robusta.dev/litellm/model_prices_and_context_window.json

LITELLM_COST_MAP_REFRESH_INTERVAL_SECONDS

LiteLLM downloads its model catalog once at startup, so a model released while Holmes is running is missing from it until a restart. When a lookup for a model's context window, max output tokens, or pricing finds nothing, Holmes re-downloads the catalog, at most once per this interval.

Default: 86400 (once a day)

HOLMES_CONFIG_PATH

Path to a custom HolmesGPT configuration file. If not set, defaults to ~/.holmes/config.yaml.

Example:

export HOLMES_CONFIG_PATH="/path/to/custom/config.yaml"

LOG_LEVEL

Controls the logging verbosity of HolmesGPT.

Values: DEBUG, INFO, WARNING, ERROR, CRITICAL Default: INFO

Example:

export LOG_LEVEL="DEBUG"

ENABLE_JSON_LOGS_FORMAT

When enabled, HolmesGPT emits logs as JSON (one object per line) instead of the default colored text format. This makes logs easier to index, search, and filter with log scrapers such as Filebeat.

Default: false

Example:

export ENABLE_JSON_LOGS_FORMAT="true"

SCOPED_NAMESPACES

Comma-separated list of namespaces this Holmes instance's Kubernetes RBAC is limited to. When set, Holmes is told its access scope in the system prompt, so investigations start scoped to those namespaces instead of discovering the restriction from Forbidden errors. The Helm chart sets it automatically when namespaceScopedRBAC is enabled; set it yourself when scoping RBAC manually.

Default: unset (cluster-wide access assumed)

Example:

export SCOPED_NAMESPACES="monitoring"        # single namespace
export SCOPED_NAMESPACES="monitoring,default"  # multiple namespaces

TRACE_TOKEN_USAGE

When enabled, logs aggregated token usage (input, output, cached, total, cost) once per completed /api/chat request at INFO level. Useful for debugging token consumption and cost issues.

Default: false

Example:

export TRACE_TOKEN_USAGE="true"

Sample output:

Completed /api/chat request: ask=... (stream) | model=gpt-4o, input=45290, output=603, cached=0, total=45893, cost=$0.0656

HOLMES_CACHE_DIR

Directory for caching HolmesGPT data and temporary files.

HOLMES_PASSTHROUGH_BLOCKED_HEADERS

Default: "authorization,cookie,set-cookie"

Comma-separated list of HTTP header names that should not be forwarded from incoming requests to toolsets via request_context. Case-insensitive.

Example:

# Also block a custom internal header
export HOLMES_PASSTHROUGH_BLOCKED_HEADERS="authorization,cookie,set-cookie,x-internal-only"

See HTTP Header Propagation for details.

HOLMES_CONNECTIVITY_CHECK_ALLOW_ALL_HOSTS

Default: false

When set to true, the connectivity_check toolset's tcp_check tool may probe private/internal destinations without them being listed in its allowed_hosts setting. Use it if you don't want to maintain an allowlist — at your own risk: the model picks the host and port, and tcp_check's open/refused/filtered outcomes make that a usable network scanner if an investigation reads attacker-controlled text. A warning is logged at startup while it is on.

Cloud-metadata (169.254.169.254), loopback and link-local targets remain blocked — this variable never unblocks them. The one setting that does is block_internal_ips: false, which removes those checks independently of this variable; a deployment that sets both gets the unrestricted behaviour of block_internal_ips: false. block_private_ips: true still overrides this. While it is on, any configured allowed_hosts entries are ignored entirely — they neither restrict destinations nor exempt one from the metadata/loopback block. Equivalent to setting allow_all_hosts: true in the toolset config.

Example:

export HOLMES_CONNECTIVITY_CHECK_ALLOW_ALL_HOSTS=true

See Connectivity Check for details.

Data Source Configuration

Prometheus

• PROMETHEUS_URL - URL of the Prometheus server

Confluence

• CONFLUENCE_API_URL - Base URL of Confluence instance (e.g., https://mycompany.atlassian.net)
• CONFLUENCE_USER - User email (Cloud) or username (Data Center) for authentication
• CONFLUENCE_API_KEY - API token (Cloud) or password (Data Center)
• CONFLUENCE_PAT - Personal Access Token (Data Center, used with auth_type: bearer)

GitHub

• GITHUB_TOKEN - Personal access token for GitHub API

Datadog

• DATADOG_APP_KEY - Datadog application key
• DATADOG_API_KEY - Datadog API key

AWS

• AWS_ACCESS_KEY_ID - AWS access key (also used for AWS toolset)
• AWS_SECRET_ACCESS_KEY - AWS secret key (also used for AWS toolset)
• AWS_DEFAULT_REGION - Default AWS region

MongoDB Atlas

• MONGODB_ATLAS_PUBLIC_KEY - Public key for MongoDB Atlas API
• MONGODB_ATLAS_PRIVATE_KEY - Private key for MongoDB Atlas API

Slab

• SLAB_API_KEY - API key for Slab integration

Remote MCP Servers

MCP_TOOL_CALL_TIMEOUT_SEC

Default: 120 (falls back to SSE_READ_TIMEOUT)

Per-request timeout, in seconds, for MCP tool calls. Forwarded to the MCP SDK's ClientSession.call_tool(read_timeout_seconds=...), which enforces it via anyio.fail_after around the response-stream receive. Without a bound here, streamable-http tool calls can hang indefinitely if the MCP server dies mid-response (the httpx/anyio stream EOF does not reliably wake pending response futures).

On expiry the SDK raises McpError(code=REQUEST_TIMEOUT), which Holmes surfaces as a StructuredToolResultStatus.ERROR result with the message Timed out while waiting for response to ClientRequest. Waited N seconds.

Example:

export MCP_TOOL_CALL_TIMEOUT_SEC=60

Testing and Development

RUN_LIVE

Enables live execution of commands in tests. Defaults to true.

Example:

export RUN_LIVE=true

MODEL

Override the default LLM model for testing.

Example:

export MODEL="anthropic/claude-sonnet-4-20250514"

CLASSIFIER_MODEL

Model to use for scoring test answers (defaults to MODEL if not set). Required when using Anthropic models as the primary model since Anthropic models cannot be used as classifiers.

Example:

export CLASSIFIER_MODEL="gpt-4.1"

ITERATIONS

Number of times to run each test for reliability testing.

Example:

export ITERATIONS=10

BRAINTRUST_API_KEY

API key for Braintrust integration to track test results.

BRAINTRUST_ORG

Braintrust organization name (default: "robustadev").

EXPERIMENT_ID

Custom experiment name for tracking test runs in Braintrust.

ASK_HOLMES_TEST_TYPE

Controls message building flow in ask_holmes tests: - cli (default) - Uses CLI-style message building - server - Uses server-style message building with ChatRequest

See Also

• AI Providers - Detailed configuration for each AI provider
• CLI Installation - Setting up the CLI with environment variables
• Helm Configuration - Kubernetes deployment configuration