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.

This guide walks you through cloning the repository, building the tclp binary, writing a minimal configuration file, and starting the proxy so that a Temporal worker can connect and route calls to your Temporal Cloud namespace. By the end you will have a running proxy instance that authenticates to Temporal Cloud using an API key, accepts plain gRPC connections from workers on port 7233, and exposes Prometheus metrics on port 9090.
1

Clone the repository and build the binary

Clone the project from GitHub, change into the directory, and run make build to compile the tclp binary. Go 1.24 or later is required.
git clone https://github.com/temporal-sa/temporal-cloud-proxy.git
cd temporal-cloud-proxy
make build
A successful build produces the ./tclp binary in the repository root:
ls -lh tclp
# -rwxr-xr-x  1 user  staff   9.8M  tclp
2

Copy the sample configuration

The repository ships with a fully annotated sample configuration. Copy it to config.yaml as the starting point for your setup.
cp config.sample.yaml config.yaml
The sample file contains commented-out blocks for every optional feature (encryption, worker auth) so you can enable them incrementally without looking up syntax.
3

Write a minimal config.yaml

Replace the placeholder values in config.yaml with your Temporal Cloud details. The example below configures one workload that authenticates to Temporal Cloud using an API key read from the environment variable TEMPORAL_API_KEY. No worker authentication or payload encryption is enabled at this stage — those can be added later.
server:
  port: 7233
  host: "0.0.0.0"

metrics:
  port: 9090

encryption:
  caching:
    max_cache: 100
    max_age: "10m"
    max_usage: 100

workloads:
  - workload_id: "my-workload"
    temporal_cloud:
      namespace: "my-namespace.my-account"
      host_port: "us-east-1.aws.api.temporal.io:7233"
      authentication:
        api_key:
          env: TEMPORAL_API_KEY
The required fields for each workload are:
FieldDescription
workload_idUnique identifier workers pass in the workload-id gRPC header
temporal_cloud.namespaceYour Temporal Cloud namespace (e.g. my-namespace.my-account)
temporal_cloud.host_portTemporal Cloud gRPC endpoint including port
temporal_cloud.authenticationEither api_key or tls — not both
Export the API key before starting the proxy:
export TEMPORAL_API_KEY="your-temporal-cloud-api-key"
4

Run the proxy

Start the proxy by passing the path to your configuration file:
./tclp --config config.yaml
On a successful start you will see structured log output similar to the following:
{"level":"info","ts":1700000000.123,"caller":"transport/transport.go:52","msg":"proxy started","host":"0.0.0.0","port":7233}
The proxy is now:
  • Listening for inbound gRPC connections on 0.0.0.0:7233 (no TLS — workers connect in plaintext)
  • Exposing Prometheus metrics at http://localhost:9090/metrics
  • Maintaining a single TLS connection pool toward your Temporal Cloud namespace
5

Configure your Temporal worker

Temporal workers must include a workload-id gRPC metadata header on every call. The value must match the workload_id defined in your proxy configuration.Point your Temporal SDK client at the proxy instead of Temporal Cloud directly, and attach the header. The exact mechanism varies by SDK — below are two common patterns.Go SDK
import (
    "go.temporal.io/sdk/client"
    "google.golang.org/grpc/metadata"
)

c, err := client.Dial(client.Options{
    HostPort:  "localhost:7233",   // proxy address
    Namespace: "my-namespace.my-account",
    HeadersProvider: client.HeadersProviderFunc(func() (map[string]string, error) {
        return map[string]string{
            "workload-id": "my-workload",
        }, nil
    }),
})
Java SDK
WorkflowServiceStubsOptions stubsOptions = WorkflowServiceStubsOptions.newBuilder()
    .setTarget("localhost:7233")
    .addGrpcMetadataProvider(() ->
        Metadata.of("workload-id", "my-workload"))
    .build();
When worker authentication is also configured on the workload, include an authorization: Bearer <token> header alongside workload-id.
To enable verbose debug logging — which prints the full gRPC method, incoming metadata, and routing decisions for every request — pass the --level flag:
./tclp --config config.yaml --level debug
Available log levels are debug, info, warn, and error. The default is info.

​
Next Steps

With the proxy running, you can progressively harden and extend your configuration using the guides below.

Configure Multiple Workloads

Add additional workload entries to route different teams or environments through the same proxy instance.

Namespace Authentication

Switch from API key to mTLS client certificates, or learn how to reference secrets from environment variables.

Worker Authentication

Require workers to present a JWT or SPIFFE JWT-SVID before the proxy forwards their calls to Temporal Cloud.

Payload Encryption

Enable transparent AES-GCM envelope encryption via AWS KMS or GCP KMS, with configurable key caching.

Build docs developers (and LLMs) love

Get started for freeTalk to us