Server Configuration Reference

Complete reference for Temporal Server configuration options

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:

1. Config directory (legacy): Multiple YAML files in a directory structure
2. Single config file: Using --config-file flag or TEMPORAL_SERVER_CONFIG_FILE_PATH environment variable
3. 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"

See Also

• Dynamic Config Reference
• Environment Variables
• Database Schema Reference
• CLI Commands