Temporal Proxy
Temporal Proxy is a gRPC intermediary between your Temporal SDK Clients, Workers, CLI, or self-hosted Temporal Web UI and one or more upstream Temporal Services. Applications connect to one gateway endpoint. The proxy can then route each request, translate its Namespace, authenticate and authorize the caller, present upstream credentials, and encrypt supported Payload fields.
Use these pages to evaluate the prerelease project, run it against Temporal Cloud, and understand the operational and security work required before placing it in a request path.
Decide whether to use Temporal Proxy
Temporal Proxy centralizes connection and data-handling concerns that would otherwise live in every application. It is most useful when you need one or more of the following outcomes:
| Goal | What the proxy does | Boundary to plan for |
|---|---|---|
| Keep environment-specific connection details out of application configuration | Adds upstream TLS, credentials, and Namespace translation | Applications can still bypass the proxy unless you restrict their upstream credentials and network paths |
| Route applications to more than one Temporal Service | Selects an upstream by local Namespace and request metadata | The proxy becomes part of the request path and needs its own availability and capacity plan |
| Apply a common inbound access policy | Allows selected gRPC services and supports built-in or external authentication and authorization | The policy covers calls that enter the gateway, not direct calls to an upstream |
| Encrypt Payloads before they reach the Temporal Service | Applies envelope encryption to codec-capable Payload fields | Search Attributes and other non-Payload fields remain visible; existing plaintext Payloads remain readable during migration |
If one of these controls must be mandatory, treat the proxy as one layer in a larger security boundary. Restrict direct access to every upstream in addition to configuring the proxy. See Plan a Temporal Proxy deployment before evaluating it with production-shaped traffic.
Understand request handling
The proxy consists of one gateway and one per-upstream proxy server, connected by Unix sockets:
For each request, the gateway:
- Reads the target method and Namespace without decoding Payloads.
- Applies configured inbound authentication or authorization to that target.
- Rejects the call if its gRPC service is not allowed.
- Selects the first matching route, the system route for Namespace-less calls, or the default route.
- Sends the call to the selected per-upstream proxy.
The per-upstream proxy translates the local Namespace, resolves the destination, attaches TLS and credentials, and forwards the call. When payload encryption is enabled, it also encrypts supported Payloads on outbound calls and decrypts recognized encrypted Payloads on responses. See Encrypt Payloads for the exact encryption coverage and fail-closed behavior.
Choose a deployment model
You can run the gateway as a shared service or place a proxy beside each application deployment:
| Model | Prefer it when | Account for |
|---|---|---|
| Shared service | Several application deployments need the same routing and policy | Independent scaling, a larger failure domain, and securing the application-to-proxy network path |
| Sidecar or local proxy | You want a local endpoint and failure isolation per application deployment | More proxy instances, configuration distribution, and coordinated application rollouts |
Both models require enough instances, capacity, and regional placement for the availability of the upstreams they serve. Plan a Temporal Proxy deployment covers topology, trust boundaries, bypass prevention, and high availability.
Choose your next step
| If you want to | Start here |
|---|---|
| Run the checked-in example against Temporal Cloud | Get started with Temporal Cloud |
| Decide where the proxy belongs and which traffic it must cover | Plan a Temporal Proxy deployment |
| Build a complete configuration | Configure Temporal Proxy |
| Route traffic and translate Namespace names | Route requests and translate Namespaces |
| Configure TLS, authentication, authorization, and credentials | Secure connections and authorize requests |
| Encrypt supported Payload fields | Encrypt Payloads |
| Rotate or retire encryption keys | Manage encryption keys |
| Install the Helm chart | Deploy Temporal Proxy to Kubernetes |
| Monitor or diagnose a deployment | Operate and troubleshoot Temporal Proxy |
| Look up flags, configuration sections, metrics, or compatibility | Temporal Proxy reference |
Install the proxy
Choose an installation method that matches your evaluation environment. Pin a release instead of using a moving tag when you need repeatable behavior.
Install the proxy binary with Go:
go install github.com/temporalio/temporal-proxy/cmd/proxy@vX.Y.Z
Pull the container image:
docker pull temporalio/temporal-proxy:vX.Y.Z
Install the Helm chart from the Temporal chart repository:
helm install temporal-proxy temporal-proxy \
--repo https://go.temporal.io/helm-charts \
--version <chart-version>
See the Temporal Proxy releases and Helm chart releases for available versions. The reference page lists runtime flags and configuration sections.
Review terminology
| Term | Meaning |
|---|---|
| gateway | The single inbound gRPC endpoint. It admits and routes requests without decoding Payloads. |
| upstream | A configured Temporal Service or another Temporal Proxy that receives forwarded calls. |
| system upstream | The upstream for Namespace-less calls such as GetSystemInfo. |
| per-upstream proxy | The internal server that applies translation, credentials, TLS, and optional payload encryption for one upstream definition. |
| extension server | A gRPC service you operate that wraps encryption keys or makes inbound authorization decisions. |