temporal-proxy

Temporal Proxy (Pre-release)

A gRPC proxy that sits between Temporal SDK Clients, Workers, and the Temporal UI on one side and one or more upstream Temporal Services on the other. It handles Namespace translation, TLS termination, and payload encryption so applications can target a single local endpoint while the proxy fans requests out to the right upstream (a local dev Temporal Service, a self-hosted deployment, Temporal Cloud, or some mix).

[!NOTE]

Pre-release: This project is under active development and evolving quickly. It is not ready for production use. Open a GitHub issue if you have questions or want to follow along.

Why

Connection details leak into application code. Every Worker and Client has to know the upstream's host, TLS material, credentials, and the exact Namespace name the upstream expects. That couples your code to an environment and makes moving between a local Temporal Service, a self-hosted deployment, and Temporal Cloud a code change.

The proxy pulls that concern out. Workers talk plaintext to a single local endpoint using a short Namespace name; the proxy owns TLS, credentials, and Namespace translation on the way out. Point a Worker at a different Namespace and it reaches a different upstream with no change to the Worker.

How

  flowchart LR
    Worker[Worker]
    Client[SDK Client]
    UI[Web UI]

    subgraph Proxy[Temporal Proxy]
        direction LR
        Gateway["Gateway<br/>routes by Namespace<br/>codec-transparent (no payload parsing)"]
        ProxyA["Per-upstream proxy A<br/>Namespace translation<br/>payload encryption (optional)"]
        ProxyB["Per-upstream proxy B<br/>Namespace translation<br/>payload encryption (optional)"]
        Gateway -->|unix socket| ProxyA
        Gateway -->|unix socket| ProxyB
    end

    Cloud[Temporal Cloud]
    SelfHosted[Self-hosted Temporal Service]

    Worker --> Gateway
    Client --> Gateway
    UI --> Gateway
    ProxyA --> Cloud
    ProxyB --> SelfHosted

Features

• Rule-based routing. Route requests to different upstreams by Namespace and/or request metadata, with a system upstream for Namespace-less calls and a default fallback.
• Service allowlist. Forward only the gRPC services you name, defaulting to WorkflowService and OperatorService. Server reflection is opt-in, and a service you leave out is never forwarded.
• Namespace translation. Rewrite local Namespace names to the names an upstream expects (prefix, suffix, or explicit overrides) in both requests and responses.
• TLS termination and outbound credentials. Terminate inbound TLS/mTLS and attach the upstream's own TLS and credentials (API key or mTLS), so client code carries none of it.
• Payload encryption. Optionally seal payloads with envelope encryption on the hop to an upstream and open them on responses, so the upstream only ever sees ciphertext while local Workers keep exchanging cleartext. DEKs are wrapped by a KMS key (AWS KMS, Azure Key Vault, or GCP KMS), rotate automatically, and can be overridden per Namespace.
• Pluggable key management. For a backend the proxy has no built-in support for, such as an on-prem HSM or an internal key service, point it at an extension server you run and it wraps DEKs through that instead. Only key material is exchanged; payloads never reach it.
• Inbound authentication and authorization. Optional static-token or JWKS validation on the gateway; off by default. For rules neither covers, delegate the decision to an extension server you run. It is told what the call is addressing (the gRPC method, and the Namespace the proxy resolved from the request rather than from anything the caller claims), so it can decide per Namespace and per method rather than only whether the caller is who it says it is.
• Prometheus metrics. Expose request latency and counts, routing decisions, and payload sealing and opening on /metrics. The listen address and the metric prefix stamped onto every metric name are set under metrics: in the config, along with the labels every series carries: constants such as the region the proxy runs in, and request metadata carried onto the request-scoped series, so they can be sliced by a dimension only your callers know.
• Codec-transparent. The gateway never parses payloads. It peeks the Namespace, picks an upstream, and relays raw frames in both directions.
• Multiple deployment options. Ship as a Go binary, a container image, or a Helm chart.

Installation

Go

Install the proxy binary into your $GOBIN with go install:

go install github.com/temporalio/temporal-proxy/cmd/proxy@latest

@latest resolves to the newest stable release. Pin an explicit version from the releases page if you prefer:

go install github.com/temporalio/temporal-proxy/cmd/proxy@vX.Y.Z

Container image

Images are published to Docker Hub:

docker pull temporalio/temporal-proxy:latest

Helm

A chart is published to the Temporal Helm repo at https://go.temporal.io/helm-charts:

# Latest stable release
helm install temporal-proxy temporal-proxy \
  --repo https://go.temporal.io/helm-charts

# Or pin a specific proxy version (see the releases page)
helm install temporal-proxy temporal-proxy \
  --repo https://go.temporal.io/helm-charts \
  --set image.tag=vX.Y.Z

Each chart release deploys a proxy version by default; --set image.tag overrides it to pin a specific one.

Supply the proxy config under the config: key in a values file and pass it with -f:

# values.yaml
config:
  hostPort: :7233
  upstreams:
    - name: local
      hostPort: localhost:7234
      insecure: true
  routing:
    default: local

helm install temporal-proxy temporal-proxy \
  --repo https://go.temporal.io/helm-charts \
  -f values.yaml

See the chart README for the full set of options.

Get started

The Temporal Cloud example is the quickest way to see the proxy in action: a Worker and starter that carry no Cloud configuration talk plaintext to localhost:7233, and the proxy adds TLS, the API key, and the Namespace rewrite on the way to Cloud. Follow its README to run it end to end.

The KMS extension server example shows the pluggable key management path end to end: a local dev server, a key provider you run, and Workflow payloads that the Temporal Service only ever stores as ciphertext. It is built on pkg/ext, which supplies the gRPC surface, the credential check, TLS, and graceful shutdown, so writing your own extension server means implementing the key handling and little else.

The authorization example does the same for access control: an extension server maps a JWT to claims and then decides each call against them, the two steps Temporal OSS splits across its ClaimMapper and Authorizer. Four tokens show what that buys, including a Worker that cannot reach a second Namespace and an auditor that can read history but not start a Workflow.

Metrics

The proxy serves Prometheus metrics on /metrics. Everything under metrics: in the config controls the endpoint and how series are labeled:

Published series

Every name below is prefixed with the metric prefix and its subsystem, so requests_total in the server subsystem is exposed as tmprl_proxy_server_requests_total by default. Each configured metadata label is added to the series emitted while serving a request: the server and router series, and vault_ops. The KEK and DEK series do not carry them, because they are emitted off the request path where no metadata is in scope to read. A fixed label is added to every series in the table, and to nothing registered outside the proxy's own collectors, so the runtime's go_* and process_* series stay as they are.

The encryption subsystem only reports once encryption keys are configured.

Labels and cardinality

namespace is always declared and reports an empty value when it is turned off. Prometheus treats an empty label value as the label not being there, so turning it on leaves the shape of a query that already ignores it unchanged.

namespace is the local Namespace the Client asked for, before any Namespace translation, which is the same name you write under encryption.overrides. Two proxies fronting different Temporal Services can therefore both report a Namespace called default, so a shared Prometheus needs something else to tell those series apart: a labels.fixed entry, or a label from the scrape job.

labels.namespace is off by default because the label is unbounded: the value comes from the request, so every distinct Namespace a Client names becomes another series. Turn it on when you know that set is small. method is bounded the same way, only for trusted callers, which is why the gateway should not be exposed directly to untrusted Clients.

A labels.metadata entry is unbounded for the same reason, and it multiplies every request-scoped series rather than adding to them, so name a header whose values you know. Two things to know before naming one: /metrics is served unauthenticated, so a header carrying a credential publishes it, and a name that collides with a label a series already declares fails at startup with a message naming the collision.

A labels.fixed entry costs no cardinality, since its value never varies, which is what makes it the right place for a per-installation fact like a region, a zone, or a cluster name. It is also the only shape that reaches the KEK and DEK series. The same collision rule applies, and one more: a name a labels.metadata entry already reports under is refused, because Prometheus rejects a collector whose constant labels clash with its variable ones.

Stability

These names and labels are a published contract, pinned by a test that fails on any change to them. Renames ship with a release note.

Terms

Development

See .github/CONTRIBUTING.md for the dev loop. The common entry points are mise run test, mise run lint, and mise run format.

Security

See SECURITY.md for how to report vulnerabilities.

License

MIT, see LICENSE.