Configuration

Background

Keep is highly configurable through environment variables. This allows you to customize various aspects of both the backend and frontend components without modifying the code. Environment variables can be set in your deployment environment, such as in your Kubernetes configuration, Docker Compose file, or directly on your host system.

Backend Environment Variables

General

General configuration variables control the core behavior of the Keep server. These settings determine fundamental aspects such as the server’s host, port, and whether certain components like the scheduler and consumer are enabled.

Env var	Purpose	Required	Default Value	Valid options
KEEP_HOST	Specifies the host for the Keep server	No	”0.0.0.0”	Valid hostname or IP address
PORT	Specifies the port on which the backend server runs	No	8080	Any valid port number
SCHEDULER	Enables or disables the workflow scheduler	No	”true"	"true” or “false”
CONSUMER	Enables or disables the consumer	No	”true"	"true” or “false”
KEEP_VERSION	Specifies the Keep version	No	”unknown”	Valid version string
KEEP_API_URL	Specifies the Keep API URL	No	Constructed from HOST and PORT	Valid URL
KEEP_STORE_RAW_ALERTS	Enables storing of raw alerts	No	”false"	"true” or “false”
TENANT_CONFIGURATION_RELOAD_TIME	Time in minutes to reload tenant configurations	No	5	Positive integer
KEEP_LIVE_DEMO_MODE	Keep will simulate incoming alerts and other activity	No	”false"	"true” or “false”

Logging and Environment

Logging and environment configuration determines how Keep generates and formats log output. These settings are crucial for debugging, monitoring, and understanding the behavior of your Keep instance in different environments.

Env var	Purpose	Required	Default Value	Valid options
LOG_LEVEL	Sets the logging level for the application	No	”INFO"	"DEBUG”, “INFO”, “WARNING”, “ERROR”, “CRITICAL”
ENVIRONMENT	Specifies the environment the application is running in	No	”production"	"development”, “staging”, “production”
LOG_FORMAT	Specifies the log format	No	”open_telemetry"	"open_telemetry”, “dev_terminal”
LOG_AUTH_PAYLOAD	Enables logging of authentication payload	No	”false"	"true” or “false”

Database

Database configuration is crucial for Keep’s data persistence. Keep supports various database backends through SQLAlchemy, allowing flexibility in choosing and configuring your preferred database system.

Env var	Purpose	Required	Default Value	Valid options
DATABASE_CONNECTION_STRING	Specifies the database connection URL	Yes	None	Valid SQLAlchemy connection string
DATABASE_POOL_SIZE	Sets the database connection pool size	No	5	Positive integer
DATABASE_MAX_OVERFLOW	Sets the maximum overflow for the connection pool	No	10	Positive integer
DATABASE_ECHO	Enables SQLAlchemy echo mode for debugging	No	False	Boolean (True/False)
DB_CONNECTION_NAME	Specifies the Cloud SQL connection name	No	”keephq-sandbox:us-central1:keep”	Valid Cloud SQL connection string
DB_NAME	Specifies the Cloud SQL database name	No	”keepdb”	Valid Cloud SQL database name
DB_SERVICE_ACCOUNT	Service account for database impersonation	No	None	Valid service account email
DB_IP_TYPE	Specifies the Cloud SQL IP type	No	”public"	"public”, “private” or “psc”
SKIP_DB_CREATION	Skips database creation and migrations	No	”false"	"true” or “false”

Resource Provisioning

Resource provisioning settings control how Keep sets up initial resources. This configuration is particularly important for automating the setup process and ensuring that necessary resources are available when Keep starts.

To elaborate on resource provisioning and its configuration, please see provisioning docs.

Env var	Purpose	Required	Default Value	Valid options
PROVISION_RESOURCES	Enables or disables resource provisioning	No	”true"	"true” or “false”

Authentication

Authentication configuration determines how Keep verifies user identities and manages access control. These settings are essential for securing your Keep instance and integrating with various authentication providers.

For specific authentication type configuration, please see authentication docs.

Env var	Purpose	Required	Default Value	Valid options
AUTH_TYPE	Specifies the authentication type	No	”NOAUTH"	"AUTH0”, “KEYCLOAK”, “DB”, “NOAUTH”, “OAUTH2PROXY”, “OKTA”, “ONELOGIN”
KEEP_JWT_SECRET	Secret key for JWT token generation and validation (DB auth only)	Yes	None	Any strong secret string
KEEP_DEFAULT_USERNAME	Default username for the admin user (DB auth only)	No	”keep”	Any valid username string
KEEP_DEFAULT_PASSWORD	Default password for the admin user (DB auth only)	No	”keep”	Any strong password string
KEEP_FORCE_RESET_DEFAULT_PASSWORD	Forces reset of default user password	No	”false"	"true” or “false”
KEEP_DEFAULT_API_KEYS	Comma-separated list of default API keys to provision	No	""	Format: “name:role:secret,name:role:secret”

Service Mesh (Internal Alert Ingestion)

These settings allow trusted services within the same Kubernetes cluster to POST alerts to Keep without requiring a Keep API key. This is intended for service-to-service communication where network-level authentication (e.g. Istio mTLS with AuthorizationPolicy) ensures only authorized callers can reach Keep’s alert ingestion endpoints.

Env var	Purpose	Required	Default Value	Valid options
KEEP_ALLOW_MESH_ALERT_INGESTION	Allows unauthenticated POST requests to `/alerts/event*` endpoints	No	”false"	"true” or “false”

When KEEP_ALLOW_MESH_ALERT_INGESTION is set to "true", requests to /alerts/event* that do not carry an API key or bearer token are accepted and authenticated as an internal service with the webhook role. Calling services can optionally set the X-Service-Name HTTP header to identify themselves in Keep’s logs and audit trail:

curl -X POST http://keep-backend:8080/alerts/event \
  -H "Content-Type: application/json" \
  -H "X-Service-Name: my-service" \
  -d '[{"id":"alert-1","name":"Example Alert","severity":"info","status":"firing","source":["my-service"]}]'

The authenticated entity will have:

email: service:<X-Service-Name header value> (defaults to service:unknown if the header is not set)
role: webhook (grants write:alert and write:incident scopes)

This feature bypasses API key authentication for the alert ingestion endpoints. You must pair it with network-level access control (such as Istio AuthorizationPolicy) to restrict which services can reach these endpoints. Without network-level enforcement, any client that can reach Keep’s backend can POST alerts.

Secrets Management

Secrets Management configuration specifies how Keep handles sensitive information. This is crucial for securely storing and accessing confidential data such as API keys and integrations credentials.

Env var	Purpose	Required	Default Value	Valid options
SECRET_MANAGER_TYPE	Defines the type of secret manager to use	Yes	”FILE"	"FILE”, “GCP”, “K8S”, “VAULT”, “DB”
SECRET_MANAGER_DIRECTORY	Directory for storing secrets when using file-based secret management	No	”/state”	Any valid directory path

OpenTelemetry

OpenTelemetry configuration enables comprehensive observability for Keep. These settings allow you to integrate Keep with various monitoring and tracing systems, enhancing your ability to debug and optimize performance.

Env var	Purpose	Required	Default Value	Valid options
OTEL_SERVICE_NAME	OpenTelemetry service name	No	”keep-api”	Valid service name string
SERVICE_NAME	Alternative for OTEL_SERVICE_NAME	No	”keep-api”	Valid service name string
OTEL_EXPORTER_OTLP_ENDPOINT	OpenTelemetry collector endpoint	No	None	Valid URL
OTLP_ENDPOINT	Alternative for OTEL_EXPORTER_OTLP_ENDPOINT	No	None	Valid URL
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	OpenTelemetry traces endpoint	No	None	Valid URL
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OpenTelemetry logs endpoint	No	None	Valid URL
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	OpenTelemetry metrics endpoint	No	None	Valid URL
CLOUD_TRACE_ENABLED	Enables Google Cloud Trace exporter	No	”false"	"true” or “false”
METRIC_OTEL_ENABLED	Enables OpenTelemetry metrics	No	""	"true” or “false”

WebSocket Server (Pusher/Soketi)

WebSocket server configuration controls real-time communication capabilities in Keep. These settings are important for enabling features that require instant updates and notifications.

Env var	Purpose	Required	Default Value	Valid options
PUSHER_DISABLED	Disables Pusher integration	No	”false"	"true” or “false”
PUSHER_HOST	Hostname of the Pusher server	No	None	Valid hostname or IP address
PUSHER_PORT	Port of the Pusher server	No	None	Any valid port number
PUSHER_APP_ID	Pusher application ID	Yes (if using Pusher)	None	Valid Pusher App ID
PUSHER_APP_KEY	Pusher application key	Yes (if using Pusher)	None	Valid Pusher App Key
PUSHER_APP_SECRET	Pusher application secret	Yes (if using Pusher)	None	Valid Pusher App Secret
PUSHER_USE_SSL	Enables SSL for Pusher connection	No	False	Boolean (True/False)
PUSHER_CLUSTER	Pusher cluster	No	None	Valid Pusher cluster name

OpenAI

OpenAI configuration is used for integrating with OpenAI services. These settings are important if you’re utilizing OpenAI capabilities within Keep for tasks such as natural language processing or AI-assisted operations.

Env var	Purpose	Required	Default Value	Valid options	Backend/Frontend
OPENAI_API_KEY	API key for OpenAI services	No	None	Valid OpenAI API key	Both
OPENAI_MODEL_NAME	Model name to use for OpenAI requests	No	”gpt-4o-2024-08-06”	Valid OpenAI model name (e.g., “gpt-4o”, “gpt-4o-mini”, …)	Both
OPEN_AI_ORGANIZATION_ID	Organization ID for OpenAI services	No	None	Valid OpenAI organization ID	Both
OPENAI_BASE_URL	Base URL for OpenAI API (useful for LiteLLM proxy)	No	None	Valid URL (e.g., “http://localhost:4000”)	Both
KEEP_AI_DISABLE_TEMPERATURE	Omit the `temperature` parameter from AI requests (some models, e.g. reasoning models, only accept the default and reject explicit values)	No	false	true / false	Backend

For various different LLM based features, we also require to set these environment variables for Keep’s frontend too.

Posthog

Posthog configuration controls Keep’s integration with the Posthog analytics platform. These settings are useful for tracking usage patterns and gathering insights about how your Keep instance is being used.

Env var	Purpose	Required	Default Value	Valid options
POSTHOG_API_KEY	API key for PostHog analytics	No	”phc_muk9qE3TfZsX3SZ9XxX52kCGJBclrjhkP9JxAQcm1PZ”	Valid PostHog API key
POSTHOG_DISABLED	Disables PostHog integration	No	”false"	"true” or “false”

Sentry

Sentry configuration controls Keep’s integration with Sentry for error monitoring and reporting. These settings are important for maintaining the stability and reliability of your Keep instance.

Env var	Purpose	Required	Default Value	Valid options
SENTRY_DISABLED	Disables Sentry integration	No	”false"	"true” or “false”

Ngrok

Ngrok configuration enables secure tunneling to your Keep instance. These settings are particularly useful for development or when you need to expose your local Keep instance to the internet securely.

Env var	Purpose	Required	Default Value	Valid options
USE_NGROK	Enables ngrok for tunneling	No	”false"	"true” or “false”
NGROK_AUTH_TOKEN	Authentication token for ngrok	No	None	Valid ngrok auth token
NGROK_DOMAIN	Custom domain for ngrok	No	None	Valid domain name

Elasticsearch

Elasticsearch configuration controls Keep’s integration with Elasticsearch for advanced search capabilities. These settings are important if you’re using Elasticsearch to enhance Keep’s search functionality and performance.

Env var	Purpose	Required	Default Value	Valid options
ELASTIC_ENABLED	Enables Elasticsearch integration	No	”false"	"true” or “false”
ELASTIC_API_KEY	API key for Elasticsearch	Yes (if using Elasticsearch)	None	Valid Elasticsearch API key
ELASTIC_HOSTS	Comma-separated list of Elasticsearch hosts	Yes (if using Elasticsearch)	None	Valid Elasticsearch host URLs
ELASTIC_USER	Username for Elasticsearch basic auth	No	None	Valid username
ELASTIC_PASSWORD	Password for Elasticsearch basic auth	No	None	Valid password
ELASTIC_INDEX_SUFFIX	Suffix for Elasticsearch index names	Yes (for single tenant)	None	Any valid string

Redis

Redis configuration specifies the connection details for Keep’s Redis instance. Redis is used for various caching and queueing purposes, making these settings important for optimizing Keep’s performance and scalability.

Env var	Purpose	Required	Default Value	Valid options
REDIS	Redis enabled	No	false	true or false
REDIS_HOST	Redis server hostname	No	”localhost”	Valid hostname or IP address
REDIS_PORT	Redis server port	No	6379	Valid port number
REDIS_DB	Redis database slot	No	0	Valid DB number
REDIS_USERNAME	Redis username	No	None	Valid username string
REDIS_PASSWORD	Redis password	No	None	Valid password string

Redis Sentinel

Redis sentinel configuration specifies the connection details for Keep’s Redis sentinel instance. Redis sentinel is used when you have a redis cluster and it acts as a broker.

Env var	Purpose	Required	Default Value	Valid options
REDIS	Redis enabled	No	false	true or false
REDIS_SENTINEL_HOSTS	Redis sentinel server(s)	No	”localhost:26379"	"host1:port1,host2:port2” (comma-separated)
REDIS_SENTINEL_SERVICE_NAME	Redis sentinel service name	No	”mymaster”	Valid service name string
REDIS_DB	Redis database slot	No	0	Valid DB number
REDIS_USERNAME	Redis username	No	None	Valid username string
REDIS_PASSWORD	Redis password	No	None	Valid password string

ARQ

ARQ (Asynchronous Task Queue) configuration controls Keep’s background task processing. These settings are crucial for managing how Keep handles long-running or scheduled tasks, ensuring efficient resource utilization and responsiveness.

Env var	Purpose	Required	Default Value	Valid options
ARQ_BACKGROUND_FUNCTIONS	Comma-separated list of background functions to run	No	None	Valid function names
ARQ_KEEP_RESULT	Duration to keep job results (in seconds)	No	3600	Positive integer
ARQ_EXPIRES	Default job expiration time (in seconds)	No	3600	Positive integer
ARQ_EXPIRES_AI	AI job expiration time (in seconds)	No	3600000	Positive integer

Rate Limiting

Rate limiting configuration controls how many requests can be made to Keep’s API endpoints within a specified time period. This helps prevent abuse and ensures system stability.

Env var	Purpose	Required	Default Value	Valid options
KEEP_USE_LIMITER	Enables or disables rate limiting	No	”false"	"true” or “false”
KEEP_LIMIT_CONCURRENCY	Sets the rate limit for API endpoints	No	”100/minute”	Format: ”/” where interval can be “second”, “minute”, “hour”, “day”

Currently, rate limiting is applied to the following endpoints:

POST /alerts/event - Generic event ingestion endpoint
POST /alerts/{provider_type} - Provider-specific event ingestion endpoints

These endpoints are rate-limited according to the KEEP_LIMIT_CONCURRENCY setting when KEEP_USE_LIMITER is enabled.

Maintenance Windows

The strategy enables the ability to manage how the alerts are handled in case of a match with the Maintenance Windows Rules.

Env var	Purpose	Required	Default Value	Valid options
MAINTENANCE_WINDOW_STRATEGY	Choose the strategy	No	”default"	"default” or “recover_previous_status”
WATCHER_LAPSED_TIME	Time in seconds to execute the alert review	No	60	Valid positive integer

Frontend Environment Variables

Frontend configuration variables control the behavior and features of Keep’s user interface. These settings are crucial for customizing the frontend’s appearance, functionality, and integration with the backend services.

General

Env var	Purpose	Required	Default Value	Valid options
API_URL	Specifies the URL of the Keep backend API	Yes	None	Valid URL
AUTH_SESSION_TIMEOUT	Specifies user session timeout in seconds. Default is 30 days.	No	2592000	Value in seconds
KEEP_HIDE_SENSITIVE_FIELDS	Hides sensitive fields	No	None	”true”, “false”
HIDE_NAVBAR_CORRELATION	Hides the correlation page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_WORKFLOWS	Hides the workflows page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_SERVICE_TOPOLOGY	Hides the service topology page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_MAPPING	Hides the mapping page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_EXTRACTION	Hides the extraction page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_MAINTENANCE_WINDOW	Hides the maintenance window page from the navigation bar in the UI	No	None	”true”
HIDE_NAVBAR_AI_PLUGINS	Hides the AI plugins page from the navigation bar in the UI	No	None	”true”
KEEP_WF_LIST_EXTENDED_INFO	Use a list instead a button to show the complete execution list	No	”true"	"true”, “false”
ALERT_SIDEBAR_FIELDS	Specifies a list of fields to show in the sidebar.	No	service,source,description,message,fingerprint,url,incidents,timeline,relatedServices	Valid list of fields

Authentication

Env var	Purpose	Required	Default Value	Valid options
AUTH_TYPE	Specifies the authentication type	No	”NOAUTH"	"AUTH0”, “KEYCLOAK”, “DB”, “NOAUTH”, “OAUTH2PROXY”, “OKTA”, “ONELOGIN”
NEXTAUTH_URL	URL for NextAuth authentication	Yes	None	Valid URL
NEXTAUTH_SECRET	Secret key for NextAuth	Yes	None	Strong secret string

Posthog

Env var	Purpose	Required	Default Value	Valid options
POSTHOG_KEY	PostHog API key for frontend analytics	No	None	Valid PostHog API key
POSTHOG_HOST	PostHog Host for frontend analytics	No	None	Valid PostHog Host

Pusher

Pusher configuration is essential for enabling real-time updates and communication in Keep’s frontend. These settings allow the frontend to establish a WebSocket connection with the Pusher server, facilitating instant updates and notifications.

Env var	Purpose	Required	Default Value	Valid options
PUSHER_DISABLED	Disables Pusher integration	No	”false"	"true” or “false”
PUSHER_HOST	Hostname of the Pusher server	No	”localhost”	Valid hostname or IP address
PUSHER_PORT	Port of the Pusher server	No	6001	Valid port number
PUSHER_APP_KEY	Pusher application key	Yes (if Pusher enabled)	“keepappkey”	Valid Pusher App Key
PUSHER_CLUSTER	Pusher cluster	No	None	Valid Pusher cluster name

Overview

AIOps

Alerts

Incidents

Workflow Automation

Alert Evaluation Engine

Providers

Deployment

Development

Keep CLI

Configuration

Background

Backend Environment Variables

General

Logging and Environment

Database

Resource Provisioning

Authentication

Service Mesh (Internal Alert Ingestion)

Secrets Management

OpenTelemetry

WebSocket Server (Pusher/Soketi)

OpenAI

Posthog

Sentry

Ngrok

Elasticsearch

Redis

Redis Sentinel

ARQ

Rate Limiting

Maintenance Windows

Frontend Environment Variables

General

Authentication

Posthog

Pusher

​Background

​Backend Environment Variables

​General

​Logging and Environment

​Database

​Resource Provisioning

​Authentication

​Service Mesh (Internal Alert Ingestion)

​Secrets Management

​OpenTelemetry

​WebSocket Server (Pusher/Soketi)

​OpenAI

​Posthog

​Sentry

​Ngrok

​Elasticsearch

​Redis

​Redis Sentinel

​ARQ

​Rate Limiting

​Maintenance Windows

​Frontend Environment Variables

​General

​Authentication

​Posthog

​Pusher

Background

Backend Environment Variables

General

Logging and Environment

Database

Resource Provisioning

Authentication

Service Mesh (Internal Alert Ingestion)

Secrets Management

OpenTelemetry

WebSocket Server (Pusher/Soketi)

OpenAI

Posthog

Sentry

Ngrok

Elasticsearch

Redis

Redis Sentinel

ARQ

Rate Limiting

Maintenance Windows

Frontend Environment Variables

General

Authentication

Posthog

Pusher