Configuration

The App Framework reads configuration from environment variables at startup. There are no config files to manage—set the variables in your environment, a .env file, or your Dockerfile, and the framework picks them up automatically.

Running apps

Local development

Use run_dev_combined() in a main.py entry point. This starts the handler and the worker in a single process, so you can iterate quickly without managing separate processes or containers:

# main.py
import asyncio
from application_sdk.main import run_dev_combined
from app.connector import MyExtractor

if __name__ == "__main__":
    asyncio.run(run_dev_combined(MyExtractor))

For local development, most environment variables have sensible defaults. The minimum required variable is ATLAN_APP_MODULE if you are starting the app via the CLI instead of run_dev_combined().

Production

In production, the handler and worker run as separate processes (typically separate Kubernetes pods). Use the application-sdk CLI with the appropriate mode:

# Handler pod — always-on, serves HTTP requests
application-sdk --mode handler

# Worker pod — executes run() and @task methods
application-sdk --mode worker

# Combined — handler + worker in one process (single-pod or SDR deployments)
application-sdk --mode combined

The ATLAN_APP_MODULE environment variable must be set for the CLI to know which App subclass to load. Set it in your Dockerfile:

ENV ATLAN_APP_MODULE=app.connector:MyExtractor

The --app CLI flag accepts the same module:ClassName format and takes precedence over ATLAN_APP_MODULE, but hardcoding the value in the Dockerfile is recommended so the app module is locked to the image.

---

Environment variables

App discovery

Variable	Required	Default	Description
ATLAN_APP_MODULE	Yes (production)	—	Python import path to your App subclass, for example app.connector:MyExtractor. Startup hard-fails if unset and --app isn't provided.
ATLAN_APP_MODE	No	combined	Run mode: worker, handler, or combined. Overridden by the --mode CLI flag.
ATLAN_APPLICATION_NAME	No	default	Application name used in object storage paths, logging, and app identification.
ATLAN_DEPLOYMENT_NAME	No	local	Deployment name. Distinguishes between environments (dev, staging, prod). Isolates object storage paths and state between deployments.
ATLAN_TENANT_ID	No	default	Tenant identifier for multi-tenant deployments.

Handler

Variable	Required	Default	Description
ATLAN_HANDLER_HOST	No	0.0.0.0	Bind address for the handler's HTTP server.
ATLAN_HANDLER_PORT	No	8000	Port the handler's HTTP server listens on. Set in your Dockerfile so the value is explicit.

Execution engine

These variables connect your app to the underlying execution engine that powers durable task execution.

Variable	Required	Default	Description
ATLAN_TEMPORAL_HOST	Yes (production)	localhost:7233	Execution engine server address as host:port.
ATLAN_TEMPORAL_NAMESPACE	Yes (production)	default	Namespace used to isolate app runs between environments.
ATLAN_AUTH_ENABLED	No	false	Enable authentication for the execution engine connection. Set to true in production.
ATLAN_DEPLOYMENT_SECRET_PATH	No	ATLAN_DEPLOYMENT_SECRETS	Path to deployment credentials in the secret store. Used when ATLAN_AUTH_ENABLED=true.
ATLAN_TEMPORAL_PROMETHEUS_BIND_ADDRESS	No	0.0.0.0:9464	Prometheus metrics endpoint for execution engine SDK metrics (app latency, task retries, worker capacity, and ~40 more).

Infrastructure components

These variables configure the named infrastructure components (state store, secret store, object store, event store) that the framework uses for credential storage, state persistence, and result publishing. They correspond to named component definitions in your infrastructure runtime configuration.

Variable	Required	Default	Description
STATE_STORE_NAME	No	statestore	Name of the state store component. Used for app checkpoints and incremental extraction state.
SECRET_STORE_NAME	No	secretstore	Name of the secret store component. Used to retrieve credentials at runtime.
DEPLOYMENT_OBJECT_STORE_NAME	No	objectstore	Name of the object store component for app outputs and artifacts.
EVENT_STORE_NAME	No	eventstore	Name of the pub/sub component for event publishing and subscription.
DEPLOYMENT_SECRET_STORE_NAME	No	deployment-secret-store	Name of the secret store component for environment-specific secrets.

SQL client

Variable	Required	Default	Description
ATLAN_SQL_USE_SERVER_SIDE_CURSOR	No	true	Use server-side cursors for SQL queries. Reduces memory usage for large result sets by streaming data instead of loading it all at once.
ATLAN_TEMPORARY_PATH	No	./local/tmp/	Local path for temporary files created during extraction.

Observability

Logging

Variable	Required	Default	Description
LOG_LEVEL	No	INFO	Log verbosity. One of DEBUG, INFO, WARNING, ERROR, CRITICAL. Set to DEBUG during development.

Traces

Variable	Required	Default	Description
ATLAN_ENABLE_OTLP_TRACES	No	false	Enable OpenTelemetry trace export.

OpenTelemetry collector

Variable	Required	Default	Description
OTEL_SERVICE_NAME	No	atlan-application-sdk	Service name as it appears in telemetry data.
OTEL_SERVICE_VERSION	No	SDK version	Service version as it appears in telemetry data. Defaults to the installed application-sdk version if unset.
OTEL_EXPORTER_OTLP_ENDPOINT	No	http://localhost:4317	OTLP collector endpoint for telemetry export.
ENABLE_OTLP_LOGS	No	false	Enable structured log export to the OTLP collector.
OTEL_RESOURCE_ATTRIBUTES	No	""	Extra resource attributes to attach to all telemetry, in key=value,key=value format. The framework always injects a standard set automatically (service.name, service.version, app.name, app.version, app.sdk_version, and others). Use this variable only to add attributes beyond those.
OTEL_WF_NODE_NAME	No	""	Node name for app telemetry (set automatically in Kubernetes).
OTEL_EXPORTER_TIMEOUT_SECONDS	No	30	Timeout for telemetry export operations.
OTEL_BATCH_DELAY_MS	No	5000	Delay between batch telemetry exports (milliseconds).
OTEL_BATCH_SIZE	No	512	Maximum records per telemetry export batch.
OTEL_QUEUE_SIZE	No	2048	Maximum size of the in-memory export queue.

SDR deployments

These variables are only relevant in SDR deployments (ENABLE_ATLAN_UPLOAD=true). In standard production deployments, observability is routed through OpenTelemetry and the parquet sink variables have no effect.

Variable	Required	Default	Description
ENABLE_ATLAN_UPLOAD	No	false	Enable uploading SDR-processed data to Atlan. Set to true in production.
UPSTREAM_OBJECT_STORE_NAME	No	objectstore	Name of the object store component for uploading data from SDR to Atlan.
ATLAN_ENABLE_OBSERVABILITY_STORE_SINK	No	true	Enable the parquet observability sink. Set to false in non-SDR deployments to route all telemetry through OTLP only.

Log storage

Variable	Required	Default	Description
ATLAN_LOG_BATCH_SIZE	No	100	Number of log records to buffer before writing to the parquet log file.
ATLAN_LOG_FLUSH_INTERVAL_SECONDS	No	10	How often (seconds) the log buffer is flushed to disk.
ATLAN_LOG_RETENTION_DAYS	No	30	How many days of log files to retain before automatic cleanup.
ATLAN_LOG_CLEANUP_ENABLED	No	false	Enable automatic cleanup of old log files.
ATLAN_LOG_FILE_NAME	No	log.parquet	Filename for the parquet log file.

Metric storage

Variable	Required	Default	Description
ATLAN_METRICS_BATCH_SIZE	No	100	Number of metric records to buffer before writing.
ATLAN_METRICS_FLUSH_INTERVAL_SECONDS	No	10	How often (seconds) metric records are flushed.
ATLAN_METRICS_RETENTION_DAYS	No	30	Days of metric history to retain.
ATLAN_METRICS_CLEANUP_ENABLED	No	false	Enable automatic cleanup of old metric files.

Cloud storage

Variable	Required	Default	Description
AWS_SESSION_NAME	No	temp-session	Session name used when assuming AWS IAM roles—for both object store access and database connections (for example, RDS IAM authentication).

---

Generated contract files

The App Framework reads generated contract JSON files at startup. These are produced by the Pkl contract tooling and committed to your repo under app/generated/.

Variable	Default	Description
ATLAN_CONTRACT_GENERATED_DIR	app/generated	Directory where generated contract JSON files are stored. Resolves to /app/app/generated inside the standard Docker image (WORKDIR=/app). Override only if your project uses a different path.

For apps with multiple entry points (using @entrypoint), generated files are organized in subfolders named after each entry point:

app/generated/
  extract-metadata/
    manifest.json
  mine-queries/
    manifest.json

---

Example .env file

A minimal local development setup. The execution engine connection variables assume you have the local infrastructure stack running (see the getting started guide for setup instructions).

# App identity
ATLAN_APPLICATION_NAME=my-postgres-connector
ATLAN_DEPLOYMENT_NAME=local
ATLAN_TENANT_ID=default

# App module (required for CLI mode; not needed when using run_dev_combined())
ATLAN_APP_MODULE=app.connector:PostgresExtractor

# HTTP server
ATLAN_HANDLER_PORT=8000

# Execution engine (local stack)
ATLAN_TEMPORAL_HOST=localhost:7233
ATLAN_TEMPORAL_NAMESPACE=default

# Generated contracts
ATLAN_CONTRACT_GENERATED_DIR=app/generated

# Logging
LOG_LEVEL=DEBUG

---

Further reading

• Apps and tasks: understanding App, @task, and how the framework runs your code
• Architecture (advanced): what the execution engine and infrastructure runtime are, and why these variables exist