Environment variables

Reference for every self-hosted Tracecat environment variable: configure auth, storage, secrets, integrations, and runtime behavior across services.

Required secrets

Secret	Purpose
TRACECAT__DB_ENCRYPTION_KEY	Fernet key for at-rest encryption in PostgreSQL. Losing it makes encrypted credentials unrecoverable.
TRACECAT__SERVICE_KEY	HMAC key for service-to-service JWT signing.
TRACECAT__SIGNING_SECRET	Signs webhook URLs and HMAC operations. Changing it invalidates existing webhook URLs and agent channel endpoint URLs.
USER_AUTH_SECRET	Secures password reset tokens, email verification tokens, and OAuth state. Derives the MCP OIDC issuer keypair and the internal OIDC client secret.

Generate all four with openssl:

# TRACECAT__SERVICE_KEY
openssl rand -hex 32

# TRACECAT__SIGNING_SECRET
openssl rand -hex 32

# USER_AUTH_SECRET
openssl rand -hex 32

# TRACECAT__DB_ENCRYPTION_KEY (Fernet-compatible base64)
openssl rand 32 | base64 | tr -d '\n' | tr '+/' '-_'

Example .env

PUBLIC_APP_URL=https://tracecat.yourdomain.com
PUBLIC_API_URL=https://tracecat.yourdomain.com/api
TRACECAT__APP_ENV=production
TRACECAT__DB_ENCRYPTION_KEY=<openssl rand 32 | base64 | tr -d '\n' | tr '+/' '-_'>
TRACECAT__SERVICE_KEY=<openssl rand -hex 32>
TRACECAT__SIGNING_SECRET=<openssl rand -hex 32>
USER_AUTH_SECRET=<openssl rand -hex 32>
TRACECAT__AUTH_SUPERADMIN_EMAIL=[e-mail]
TRACECAT__DB_SSLMODE=require
TRACECAT__POSTGRES_USER=postgres
TRACECAT__POSTGRES_PASSWORD=<secure-password>

See .env.example for all options.

Variables

Network

Variable	Default	Description
PUBLIC_APP_PORT	80	Port the reverse proxy listens on.
PUBLIC_APP_URL	http://localhost:${PUBLIC_APP_PORT}	Public URL users visit to reach the Tracecat UI.
PUBLIC_API_URL	${PUBLIC_APP_URL}/api	Public URL for the Tracecat API, used by the browser and for webhook callbacks.
INTERNAL_API_URL	http://api:8000	Internal URL that other services use to reach the API container.

Application

Variable	Default	Description
TRACECAT__APP_ENV	development	One of development, staging, or production. Controls logging detail and debug behavior.
TRACECAT__API_URL	${INTERNAL_API_URL}	API URL used by backend services. Normally matches INTERNAL_API_URL.
TRACECAT__API_ROOT_PATH	/api	Path prefix the API registers behind the reverse proxy.
TRACECAT__PUBLIC_APP_URL	${PUBLIC_APP_URL}	Public frontend URL used for links in emails and notifications.
TRACECAT__PUBLIC_API_URL	${PUBLIC_API_URL}	Public API URL used for incoming webhooks. If you expose webhooks through a tunnel (e.g. ngrok), set this to the tunnel URL.
TRACECAT__ALLOW_ORIGINS	http://localhost:3000,${PUBLIC_APP_URL}	Comma-separated list of allowed CORS origins.

PostgreSQL

Variable	Default	Description
TRACECAT__POSTGRES_USER	postgres	PostgreSQL username.
TRACECAT__POSTGRES_PASSWORD	postgres	PostgreSQL password. Change this in production.
TRACECAT__DB_URI	postgresql+psycopg://${TRACECAT__POSTGRES_USER}:${TRACECAT__POSTGRES_PASSWORD}@postgres_db:5432/postgres	Full database connection URI. Override this when using an external database.
TRACECAT__DB_SSLMODE	disable	PostgreSQL SSL mode. Set to require or verify-full for remote databases.

Authentication

Variable	Default	Description
TRACECAT__AUTH_SUPERADMIN_EMAIL		Email promoted to superadmin when that account is created. Set it before the first user registers; until then, nobody can register.
TRACECAT__AUTH_TYPES	basic	Comma-separated list of enabled auth methods: basic, oidc, saml.
TRACECAT__AUTH_ALLOWED_DOMAINS		Comma-separated email domains allowed to create an account and to sign in through OIDC, e.g. example.com,example.org. Leave blank to allow all. SAML uses the organization’s configured domains when set; without them, single-tenant deployments fall back to this list and multi-tenant deployments reject the sign-in. Membership in an organization still comes from an invitation or admin provisioning.
TRACECAT__AUTH_MIN_PASSWORD_LENGTH	12	Minimum password length for basic auth.

OIDC / OAuth

Variable	Default	Description
OIDC_ISSUER		OIDC issuer URL (e.g. https://accounts.google.com).
OIDC_CLIENT_ID		OAuth client ID from your identity provider.
OIDC_CLIENT_SECRET		OAuth client secret from your identity provider.
OIDC_SCOPES	openid profile email	Space-separated OAuth scopes to request.

SAML

Variable	Default	Description
SAML_IDP_METADATA_URL		URL to your SAML IdP metadata XML.
SAML_ACCEPTED_TIME_DIFF	3	Maximum clock skew in seconds accepted when validating SAML assertions.
SAML_ALLOW_UNSOLICITED	false	Whether to allow unsolicited SAML responses.
SAML_VERIFY_SSL_ENTITY	true	Whether to verify SSL certificates for general SAML entity operations.
SAML_VERIFY_SSL_METADATA	true	Whether to verify SSL certificates when fetching SAML metadata.
SAML_CA_CERTS		Optional base64-encoded CA bundle for validating self-signed IdP metadata TLS certificates.

Temporal

Variable	Default	Description
TEMPORAL__CLUSTER_URL	temporal:7233	Temporal cluster gRPC endpoint.
TEMPORAL__CLUSTER_QUEUE	tracecat-task-queue	Temporal task queue name.
TEMPORAL__CLUSTER_NAMESPACE	default	Temporal namespace.
TEMPORAL__API_KEY		API key for Temporal Cloud. Leave empty for self-hosted Temporal.

Executor

Variable	Default	Description
TRACECAT__EXECUTOR_BACKEND	direct	Execution strategy for actions. direct runs a subprocess per action, ephemeral spawns a cold nsjail subprocess per action for full isolation, auto selects ephemeral if nsjail is available and falls back to direct.
TRACECAT__DISABLE_NSJAIL	true	Disable nsjail sandboxing. Set to false only if nsjail is installed.
TRACECAT__RESULT_EXTERNALIZATION_ENABLED	true	Store large action results in blob storage instead of Temporal history.
TRACECAT__RESULT_EXTERNALIZATION_THRESHOLD_BYTES	128000	Byte threshold above which payloads are externalized to blob storage.
TRACECAT__WORKFLOW_ARTIFACT_RETENTION_DAYS	30	Retention period in days for workflow artifacts. Objects older than this are automatically deleted via S3 lifecycle rules. Set to 0 to disable.
TRACECAT__ACTIVITY_HEARTBEAT_TIMEOUT	60	Seconds Temporal waits for a heartbeat from an executor activity before failing it and retrying on a healthy worker. Set to 0 to disable. Read by the worker service. The Compose files and the Fargate module do not pass this variable through, so set it on that container directly. To disable heartbeats, set this and TRACECAT__ACTIVITY_HEARTBEAT_INTERVAL to 0 together.
TRACECAT__ACTIVITY_HEARTBEAT_INTERVAL	30	Seconds between heartbeats from executor activities. A value at or above TRACECAT__ACTIVITY_HEARTBEAT_TIMEOUT lets Temporal fail the activity between two heartbeats. Set to 0 to disable heartbeats. Read by the executor service and not passed through by the Compose files or the Fargate module, so set it on that container directly. 0 alone stops the executor heartbeating while the worker still expects one every TRACECAT__ACTIVITY_HEARTBEAT_TIMEOUT seconds, which fails actions that run longer than that.

Agents

Variable	Default	Description
TRACECAT__AGENT_SANDBOX_TIMEOUT	3600	Ceiling in seconds for the timeout of ai.agent, ai.action, and ai.preset_agent. Tracecat clamps explicit values between 1800 and this value, and unset means 1800. A ceiling below 1800 replaces both the floor and the default.
TRACECAT__AGENT_EXECUTOR_GRACEFUL_SHUTDOWN_TIMEOUT	3660	Seconds the agent executor worker waits for running agent activities to finish during a planned shutdown. Defaults to TRACECAT__AGENT_SANDBOX_TIMEOUT plus 60.
TRACECAT__LLM_PROXY_READ_TIMEOUT	600	Seconds the sandbox LLM proxy waits for the next byte from the model gateway before failing the request with 504. Separate from the agent timeout.

Blob storage

Variable	Default	Description
TRACECAT__BLOB_STORAGE_BUCKET_WORKFLOW	tracecat-workflow	S3 bucket for workflow artifacts.
TRACECAT__BLOB_STORAGE_BUCKET_ATTACHMENTS	tracecat-attachments	S3 bucket for case attachments.
TRACECAT__BLOB_STORAGE_BUCKET_REGISTRY	tracecat-registry	S3 bucket for registry packages.

MinIO

Variable	Default	Description
MINIO_ROOT_USER	minio	MinIO root username. Only used with the bundled MinIO instance.
MINIO_ROOT_PASSWORD	password	MinIO root password. Change this in production.

Redis

Variable	Default	Description
REDIS_HOST	redis	Redis hostname.
REDIS_PORT	6379	Redis port.
REDIS_URL	redis://${REDIS_HOST}:${REDIS_PORT}	Full Redis connection URL. Override this when using an external Redis instance.