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.
TRACECAT__TRUSTED_PROXY_CIDRS	127.0.0.1/32	Space-separated proxy CIDRs that Caddy trusts when deriving the client address from X-Forwarded-For. Set this when another proxy or load balancer runs in front of Caddy.
TRACECAT__OUTBOUND_ALLOWED_PRIVATE_CIDRS		Comma-separated IPs or CIDRs, e.g. 10.0.12.34/32,10.42.0.0/16, that custom LLM providers (LiteLLM, vLLM, Ollama, custom sources) and remote MCP servers may resolve to. Tracecat rejects private, loopback, and link-local destinations with Host is not allowed unless they are listed here. Set it on api, agent-worker, litellm, and agent-executor. See Private endpoints.
TRACECAT__AUDIT_TRUSTED_PROXY_CIDRS	loopback + private ranges	Comma-separated CIDRs of proxies behind which the API runs (Caddy, the UI container, a load balancer). X-Forwarded-For entries from these hops are skipped when resolving the client IP for audit logs.

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 mode for actions, agents, registry sync, and Python scripts. direct runs without nsjail; nsjail requires nsjail isolation. ephemeral is a compatibility alias for nsjail.
TRACECAT__SANDBOX_DEFAULT_MEMORY_MB	2048	Aggregate cgroup v2 memory limit in MiB per core.script.run_python, dependency-install, and custom action sandbox, shared by its processes. Applied by the nsjail backend. Exceeding it during script or action execution fails as sandbox.resource_limit_exceeded; an over-budget dependency installation fails as a package installation failure. The container memory limit still applies on top. See Resource limits.
TRACECAT__SANDBOX_ADDRESS_SPACE_MB	Twice the memory budget	Per-process virtual address-space cap in MiB for action, Python, and dependency-install sandboxes. Requires nsjail. Set a positive integer to override the computed default.
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.

Tunnels

Set all four on the api service to enable managed tunnels. Managed tunnels are off while any is unset.

Variable	Default	Description
TRACECAT__PANGOLIN_ENDPOINT		Pangolin server URL that site connectors and machine clients connect to, e.g. https://app.pangolin.net or https://pangolin.example.com.
TRACECAT__PANGOLIN_API_URL		Pangolin Integration API base URL ending in /v1, e.g. https://api.pangolin.net/v1.
TRACECAT__PANGOLIN_ORG_ID		Pangolin organization ID that holds every managed site, client, and resource.
TRACECAT__PANGOLIN_API_KEY		Pangolin organization API key with site, client, and private resource permissions. Store it in your secrets manager.
TRACECAT__PANGOLIN_API_KEY__ARN		AWS Secrets Manager ARN of the Pangolin API key, used instead of TRACECAT__PANGOLIN_API_KEY. Read by the api service only.

These settings control the tunnel gateways that the api service runs. Executors read TRACECAT__TUNNEL_GATEWAY_HOST_TEMPLATE and TRACECAT__TUNNEL_GATEWAY_PORT to find a tunnel’s gateway.

Variable	Default	Description
TRACECAT__TUNNEL_GATEWAY_BACKEND	none	kubernetes to have the api service create and reconcile one gateway per tunnel, or none to run gateways yourself.
TRACECAT__TUNNEL_GATEWAY_NAMESPACE	tracecat-tunnels	Kubernetes namespace for gateway Secrets, Deployments, and Services.
TRACECAT__TUNNEL_GATEWAY_IMAGE	ghcr.io/tracecathq/tracecat-tunnel-gateway:<version>	Gateway image. Defaults to the running Tracecat version; set repository@sha256:<digest> to pin an immutable image.
TRACECAT__TUNNEL_GATEWAY_BLOCKED_CIDRS		Comma-separated CIDRs gateways never dial, such as the cluster’s pod and service ranges.
TRACECAT__TUNNEL_GATEWAY_API_URL	TRACECAT__API_URL	Internal API URL that gateways load their policy from.
TRACECAT__TUNNEL_GATEWAY_HOST_TEMPLATE	tunnel-{tunnel_id}.<TRACECAT__TUNNEL_GATEWAY_NAMESPACE>.svc.cluster.local	Gateway hostname, with {tunnel_id} filled in per tunnel.
TRACECAT__TUNNEL_GATEWAY_PORT	8080	Gateway proxy port.

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.
TRACECAT__AGENT_SANDBOX_MEMORY_MB	4096	Cgroup v2 memory budget in MiB shared by an agent sandbox and its child processes. Requires nsjail and cgroup delegation. The outer container memory limit still applies. See Resource limits.
TRACECAT__AGENT_SANDBOX_ADDRESS_SPACE_MB	Twice the memory budget	Per-process virtual address-space cap in MiB for agent sandboxes. Requires nsjail; this cap is not enforced in direct mode. Set a positive integer to override the computed default.

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.
TRACECAT__BLOB_STORAGE_PRESIGNED_URL_ENDPOINT		Public base URL substituted for TRACECAT__BLOB_STORAGE_ENDPOINT in presigned URLs. Leave unset for AWS S3. A proxy in front of the store must forward the Host of TRACECAT__BLOB_STORAGE_ENDPOINT, as the bundled Caddy does.
TRACECAT__BLOB_STORAGE_SSL_VERIFY	true	Verify TLS certificates when connecting to blob storage. Set to false for self-hosted S3-compatible storage with a self-signed or unverifiable certificate. When true, botocore CA bundle settings such as AWS_CA_BUNDLE still apply.
TRACECAT__CSP_CONNECT_SRC_ORIGINS		Space- or comma-separated origins added to the UI’s CSP connect-src. Set on the ui service to the presigned S3 bucket origins when the browser uploads or fetches blobs cross-origin. Compose defaults it to the presigned endpoint.

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.