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.
• 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.

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.