Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

The Temporal Cloud Proxy is configured entirely via a YAML file passed to the binary using the --config flag (default: config.yaml). Configuration is validated at startup — if any field fails validation the proxy exits immediately with a descriptive error message listing every problem found, so you can fix them all at once. 
./tclp --config /etc/tclp/config.yaml

​
Top-level structure

The file has four top-level keys. Every key is required unless noted otherwise. 
server:
  port: 7233       # gRPC listen port
  host: "0.0.0.0" # bind address

metrics:
  port: 9090       # Prometheus HTTP port

encryption:
  caching:
    max_cache: 100   # max cached key entries (LRU)
    max_age: "10m"   # max key age (Go duration string)
    max_usage: 100   # max uses per cached key

workloads:
  - workload_id: "<id>"
    temporal_cloud: { ... }
    encryption: { ... }      # optional
    authentication: { ... }  # optional

​
server

Controls the gRPC port and bind address that Temporal workers connect to.
​
server.port
integer
required
The gRPC port the proxy listens on. Must be between 1 and 65535 inclusive. Workers and SDKs point their hostPort at this address.
​
server.host
string
required
The network interface the proxy binds to. Use "0.0.0.0" to accept connections on all interfaces, or a specific IP to restrict access.

​
metrics

Exposes a Prometheus-compatible /metrics HTTP endpoint.
​
metrics.port
integer
required
The HTTP port for the Prometheus metrics scrape endpoint. Must be between 1 and 65535 inclusive. Accessible at http://<host>:<port>/metrics.

​
encryption.caching

Global LRU cache settings that apply to every workload that has encryption enabled. These values control how long and how often the proxy reuses a data key before requesting a new one from KMS, which balances performance against key rotation frequency. 
encryption:
  caching:
    max_cache: 100
    max_age: "10m"
    max_usage: 100
​
encryption.caching.max_cache
integer
default:"100"
Maximum number of entries in the LRU key cache. When the cache is full the least-recently-used entry is evicted. Must be >= 0.
​
encryption.caching.max_age
string
default:"10m"
Maximum age of a cached key, expressed as a Go duration string (e.g. "5m", "1h", "30s"). Keys older than this value are evicted on next access and a fresh key is generated from KMS.
​
encryption.caching.max_usage
integer
default:"100"
Maximum number of times a single cached key may be used for encryption or decryption before it is evicted and regenerated. Must be >= 0. Encryption and decryption operations each maintain separate cache entries, so a key that has been used 100 times for encryption is evicted independently of decryption usage.
These caching values are global defaults shared across all workloads. There is no per-workload caching override — all workloads share the same LRU cache instance and eviction policy.

​
workloads

An array of workload definitions. Each entry maps an incoming workload-id gRPC header value to a specific Temporal Cloud namespace, along with optional payload encryption and worker authentication settings. See the Workloads page for the complete field reference and multi-workload examples.
workload_id values must be unique within the config file. If the same ID appears more than once the proxy exits at startup with the error: workload already exists: <id>.
Run the proxy with --level debug to log each incoming request’s workload-id and gRPC method name. This is useful for verifying that workers are sending the correct header and for tracing which workload configuration is being applied to each call.

​
Validation rules

The following constraints are enforced at startup. All errors are collected and reported together before the process exits.
RuleError
server.port must be 1–65535invalid server port: <n>
metrics.port must be 1–65535invalid metrics server port: <n>
encryption.caching.max_cache must be >= 0encryption max_cache must be >= 0: <n>
encryption.caching.max_usage must be >= 0encryption max_usage must be >= 0: <n>
Each workload_id must be non-emptyworkload_id is required
Each workload_id must be uniqueworkload already exists: <id>
temporal_cloud.namespace must not be blanktemporal cloud namespace must not be blank: <id>
temporal_cloud.host_port must not be blanktemporal cloud hostport must not be blank: <id>
api_key and tls cannot both be set on the same workloadcannot have both api key and mtls authentication configured on a single workload: <id>

Build docs developers (and LLMs) love

Get started for freeTalk to us