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.

Temporal Cloud Proxy (tclp) is a Go-based gRPC proxy that sits between your Temporal workers and Temporal Cloud, consolidating namespace authentication, payload encryption, and worker identity validation into a single, centrally managed service. Instead of embedding TLS certificates, API keys, or KMS credentials in every worker deployment, you configure them once in the proxy — workers connect to it over plain gRPC, attach a workload-id metadata header, and the proxy handles everything else: routing the call to the correct Temporal Cloud namespace, proving the worker’s identity, and encrypting or decrypting payloads in-flight. This makes tclp a strong fit for platform teams that manage multiple workloads across shared infrastructure and need a consistent security boundary without changing each worker’s application code.

​
Key Features

Multi-workload Routing

A single proxy instance serves any number of workloads. Each workload maps a workload-id to its own Temporal Cloud namespace, authentication method, and encryption configuration.

Namespace Authentication

Authenticate to Temporal Cloud per workload using mTLS (client certificate + key) or API keys (inline value or environment variable reference).

Worker Authentication

Validate inbound worker identity using JWT (verified against a JWKS endpoint with audience and expiry checks) or SPIFFE/SPIRE (JWT-SVID validated against an allowlist of SPIFFE IDs).

Payload Encryption

Encrypt workflow payloads transparently using AWS KMS or GCP KMS via envelope encryption (AES-GCM with a KMS-wrapped data key stored in payload metadata).

Encryption Key Caching

A configurable caching layer wraps the KMS client, bounding keys by maximum count (max_cache), age (max_age), and usage count (max_usage) to reduce KMS API call volume.

Prometheus Metrics

Built-in Prometheus metrics (request totals, error rates, latency histograms, per-workload encryption counters) exposed on a dedicated port, with a pre-built Grafana dashboard included.

​
Core Concept: Workload Routing via workload-id

Every gRPC call that arrives at the proxy must carry a workload-id value in its gRPC metadata headers. The proxy uses this value as a lookup key into its internal connectionMux map, which is built at startup from the YAML configuration. Each entry in that map holds a dedicated gRPC client connection to a Temporal Cloud namespace, the namespace’s authentication credentials, an optional worker authenticator, and an optional payload codec interceptor. If the workload-id header is absent, contains multiple values, or does not match any configured workload, the proxy returns a codes.InvalidArgument error immediately — the call never reaches Temporal Cloud. 
Worker ──► proxy:7233  (plain gRPC + workload-id header)
                │
                ▼
         connectionMux["my-workload"]
                │
                ├── validate worker auth (JWT / SPIFFE)
                ├── apply payload encryption codec
                └──► Temporal Cloud (TLS / mTLS / API key)

​
Prerequisites

Before running the proxy, ensure you have the following:
  • Go 1.24 or later — required to build from source
  • Temporal Cloud account — at least one namespace with either an API key or an mTLS client certificate provisioned
  • AWS account with KMS permissions (optional) — required only when using aws-kms payload encryption
  • GCP account with KMS permissions (optional) — required only when using gcp-kms payload encryption
  • SPIRE agent (optional) — required only when using SPIFFE worker authentication; the proxy connects to the agent over a Unix socket
Example worker implementations that demonstrate how to attach the required gRPC headers are available on GitHub:

​
Next Steps

Quickstart

Build the binary and run the proxy with a minimal one-workload configuration in under five minutes.

Configuration Reference

Explore all configuration options for workloads, namespace auth, worker auth, encryption, and caching.

Build docs developers (and LLMs) love

Get started for freeTalk to us