Server Configuration Reference

Temporal Server configuration is defined in YAML files that control all aspects of server behavior, from persistence to networking to security.

Configuration File

The server configuration can be loaded in multiple ways:

Config directory (legacy): Multiple YAML files in a directory structure
Single config file: Using --config-file flag or TEMPORAL_SERVER_CONFIG_FILE_PATH environment variable
Embedded config: Default configuration embedded in the binary

# Using config file
temporal-server start --config-file config/development.yaml

# Using environment variable
export TEMPORAL_SERVER_CONFIG_FILE_PATH=/etc/temporal/config.yaml
temporal-server start

Configuration Structure

Top-Level Configuration

Field	Type	Description
`global`	Global	Process-wide service configuration
`persistence`	Persistence	Datastore configuration
`log`	Log	Logging configuration
`clusterMetadata`	ClusterMetadata	Cluster metadata and multi-cluster setup
`dcRedirectionPolicy`	DCRedirectionPolicy	Datacenter redirection policy
`services`	map[string]Service	Per-service configuration (frontend, history, matching, worker)
`archival`	Archival	Archival configuration
`publicClient`	PublicClient	Internal service to frontend client configuration
`dynamicConfigClient`	FileBasedClientConfig	Dynamic configuration client setup
`namespaceDefaults`	NamespaceDefaults	Default settings for new namespaces
`otel`	ExportConfig	OpenTelemetry exporter configuration
`visibility`	Visibility	Visibility store configuration

Global Configuration

Membership

Cluster membership and gossip protocol configuration.

global:
  membership:
    maxJoinDuration: 10s
    broadcastAddress: ""

Field	Type	Default	Description
`maxJoinDuration`	duration	10s	Maximum time to wait to join the gossip ring
`broadcastAddress`	string	""	Address communicated to other nodes (for NAT traversal)

PProf

Go profiling endpoint configuration.

global:
  pprof:
    port: 7936
    host: localhost

Field	Type	Default	Description
`port`	int	0	Port for pprof HTTP endpoint (0 = disabled)
`host`	string	localhost	Host to bind pprof endpoint

TLS Configuration

TLS settings for inter-service and client communication.

global:
  tls:
    internode:
      server:
        certFile: /path/to/cert.pem
        keyFile: /path/to/key.pem
        requireClientAuth: true
        clientCaFiles:
          - /path/to/ca.pem
      client:
        serverName: temporal-server
        rootCaFiles:
          - /path/to/ca.pem
    frontend:
      server:
        certFile: /path/to/frontend-cert.pem
        keyFile: /path/to/frontend-key.pem
    systemWorker:
      certFile: /path/to/worker-cert.pem
      keyFile: /path/to/worker-key.pem
      client:
        serverName: temporal-frontend
        rootCaFiles:
          - /path/to/ca.pem

Server TLS

Field	Type	Description
`certFile`	string	Path to PEM-encoded certificate
`keyFile`	string	Path to PEM-encoded private key
`certData`	string	Base64-encoded certificate (alternative to certFile)
`keyData`	string	Base64-encoded private key (alternative to keyFile)
`clientCaFiles`	[]string	CA certificates for client authentication
`clientCaData`	[]string	Base64-encoded CA certificates
`requireClientAuth`	bool	Whether to require mutual TLS

Client TLS

Field	Type	Description
`serverName`	string	Expected server name for verification
`rootCaFiles`	[]string	Trusted CA certificates
`rootCaData`	[]string	Base64-encoded CA certificates
`disableHostVerification`	bool	Skip hostname verification (insecure)
`forceTLS`	bool	Use TLS even without certificates

Metrics

Metrics configuration for Prometheus, StatsD, or M3.

global:
  metrics:
    prometheus:
      listenAddress: "0.0.0.0:8000"
      handlerPath: "/metrics"

Field	Type	Description
`prometheus`	PrometheusConfig	Prometheus metrics configuration
`statsd`	StatsdConfig	StatsD metrics configuration
`m3`	M3Config	M3 metrics configuration
`tags`	map[string]string	Global tags for all metrics

Authorization

Authentication and authorization configuration.

global:
  authorization:
    jwtKeyProvider:
      keySourceURIs:
        - "https://auth.example.com/.well-known/jwks.json"
      refreshInterval: 1h
    permissionsClaimName: "permissions"
    authorizer: "default"
    claimMapper: "default"
    audience: "temporal"

Field	Type	Description
`jwtKeyProvider`	JWTKeyProvider	JWT signing key configuration
`permissionsClaimName`	string	JWT claim containing permissions
`permissionsRegex`	string	Regex to parse permissions claim
`authorizer`	string	Authorizer implementation ("" or “default”)
`claimMapper`	string	Claim mapper implementation
`authHeaderName`	string	HTTP header for auth token (default: “authorization”)
`authExtraHeaderName`	string	Additional auth header
`audience`	string	Expected JWT audience

Persistence Configuration

Database and datastore configuration.

persistence:
  defaultStore: default
  visibilityStore: visibility
  numHistoryShards: 4
  datastores:
    default:
      sql:
        pluginName: postgres
        databaseName: temporal
        connectAddr: localhost:5432
        connectProtocol: tcp
        user: temporal
        password: temporal
        maxConns: 20
        maxIdleConns: 20
        maxConnLifetime: 1h
    visibility:
      sql:
        pluginName: postgres
        databaseName: temporal_visibility
        connectAddr: localhost:5432
        connectProtocol: tcp
        user: temporal
        password: temporal
        maxConns: 10
        maxIdleConns: 10

Persistence Fields

Field	Type	Description
`defaultStore`	string	Name of default datastore for temporal data
`visibilityStore`	string	Name of datastore for visibility records
`secondaryVisibilityStore`	string	Secondary visibility store for dual writes
`numHistoryShards`	int32	Number of history shards (must be power of 2)
`datastores`	map[string]DataStore	Named datastore configurations

SQL Datastore

Field	Type	Description
`pluginName`	string	SQL plugin: “postgres”, “mysql”, “sqlite”
`databaseName`	string	Database name
`connectAddr`	string	Database host:port
`connectProtocol`	string	Connection protocol: “tcp”, “unix”
`user`	string	Database user
`password`	string	Database password
`connectAttributes`	map[string]string	Additional connection parameters
`maxConns`	int	Maximum connections
`maxIdleConns`	int	Maximum idle connections
`maxConnLifetime`	duration	Maximum connection lifetime
`taskScanPartitions`	int	Partitions for task scanning (Vitess)

Cassandra Datastore

datastores:
  default:
    cassandra:
      hosts: "127.0.0.1"
      port: 9042
      keyspace: temporal
      user: cassandra
      password: cassandra
      datacenter: datacenter1
      maxConns: 20
      connectTimeout: 600ms
      timeout: 10s

Field	Type	Description
`hosts`	string	Comma-separated Cassandra hosts
`port`	int	Cassandra port
`keyspace`	string	Keyspace name
`user`	string	Username
`password`	string	Password
`datacenter`	string	Local datacenter
`maxConns`	int	Maximum connections per host
`connectTimeout`	duration	Connection timeout
`timeout`	duration	Query timeout
`writeTimeout`	duration	Write timeout
`consistency`	CassandraConsistency	Consistency settings

Elasticsearch Datastore

datastores:
  visibility:
    elasticsearch:
      url: "https://localhost:9200"
      indices:
        visibility: temporal-visibility-dev
      username: elastic
      password: changeme

Service Configuration

Per-service settings for frontend, history, matching, and worker services.

services:
  frontend:
    rpc:
      grpcPort: 7233
      httpPort: 7243
      membershipPort: 6933
      bindOnIP: "0.0.0.0"
  history:
    rpc:
      grpcPort: 7234
      membershipPort: 6934
      bindOnIP: "0.0.0.0"
  matching:
    rpc:
      grpcPort: 7235
      membershipPort: 6935
      bindOnIP: "0.0.0.0"
  worker:
    rpc:
      grpcPort: 7239
      membershipPort: 6939
      bindOnIP: "0.0.0.0"

RPC Configuration

Field	Type	Description
`grpcPort`	int	Port for gRPC service
`httpPort`	int	Port for HTTP/gRPC-Web (frontend only)
`membershipPort`	int	Port for cluster membership
`bindOnLocalHost`	bool	Bind to localhost only
`bindOnIP`	string	Specific IP to bind (overrides bindOnLocalHost)
`httpAdditionalForwardedHeaders`	[]string	Additional headers to forward from HTTP to gRPC
`keepAliveServerConfig`	KeepAliveConfig	gRPC keepalive configuration
`clientConnectionConfig`	ClientConnectionConfig	Client connection settings

Dynamic Configuration

Dynamic configuration allows runtime configuration changes without server restart.

dynamicConfigClient:
  filepath: config/dynamicconfig/development.yaml
  pollInterval: 10s

Field	Type	Description
`filepath`	string	Path to dynamic config YAML file
`pollInterval`	duration	How often to check for config changes

Archival Configuration

History and visibility archival to long-term storage.

archival:
  history:
    state: "enabled"
    enableRead: true
    provider:
      filestore:
        fileMode: "0666"
        dirMode: "0766"
      s3store:
        region: "us-east-1"
  visibility:
    state: "enabled"
    enableRead: true
    provider:
      filestore:
        fileMode: "0666"
        dirMode: "0766"

Archival States

enabled: Archival is enabled
disabled: Archival is disabled
paused: Archival is paused temporarily

Archival Providers

filestore: Local or network filesystem
s3store: Amazon S3 or S3-compatible storage
gstorage: Google Cloud Storage

Cluster Metadata

Multi-cluster configuration.

clusterMetadata:
  enableGlobalNamespace: true
  failoverVersionIncrement: 10
  masterClusterName: "primary"
  currentClusterName: "primary"
  clusterInformation:
    primary:
      enabled: true
      initialFailoverVersion: 1
      rpcAddress: "localhost:7233"
    secondary:
      enabled: true
      initialFailoverVersion: 2
      rpcAddress: "remote-host:7233"

Field	Type	Description
`enableGlobalNamespace`	bool	Enable global namespaces
`failoverVersionIncrement`	int	Version increment for failover
`masterClusterName`	string	Name of the master cluster
`currentClusterName`	string	Name of this cluster
`clusterInformation`	map[string]ClusterInfo	Cluster details

Namespace Defaults

Default settings applied to new namespaces.

namespaceDefaults:
  archival:
    history:
      state: "disabled"
      URI: "file:///tmp/temporal-archival/history"
    visibility:
      state: "disabled"
      URI: "file:///tmp/temporal-archival/visibility"

Configuration

CLI Commands

Server Configuration Reference

Configuration File

Configuration Structure

Top-Level Configuration

Global Configuration

Membership

PProf

TLS Configuration

Server TLS

Client TLS

Metrics

Authorization

Persistence Configuration

Persistence Fields

SQL Datastore

Cassandra Datastore

Elasticsearch Datastore

Service Configuration

RPC Configuration

Dynamic Configuration

Archival Configuration

Archival States

Archival Providers

Cluster Metadata

Namespace Defaults

See Also

Build docs developers (and LLMs) love

Configuration

CLI Commands

​Configuration File

​Configuration Structure

​Top-Level Configuration

​Global Configuration

​Membership

​PProf

​TLS Configuration

​Server TLS

​Client TLS

​Metrics

​Authorization

​Persistence Configuration

​Persistence Fields

​SQL Datastore

​Cassandra Datastore

​Elasticsearch Datastore

​Service Configuration

​RPC Configuration

​Dynamic Configuration

​Archival Configuration

​Archival States

​Archival Providers

​Cluster Metadata

​Namespace Defaults

​See Also

Build docs developers (and LLMs) love

Configuration File

Configuration Structure

Top-Level Configuration

Global Configuration

Membership

PProf

TLS Configuration

Server TLS

Client TLS

Metrics

Authorization

Persistence Configuration

Persistence Fields

SQL Datastore

Cassandra Datastore

Elasticsearch Datastore

Service Configuration

RPC Configuration

Dynamic Configuration

Archival Configuration

Archival States

Archival Providers

Cluster Metadata

Namespace Defaults

See Also