# Configure Temporal Proxy

> For the complete documentation index, see [llms.txt](https://docs.temporal.io/llms.txt).
> Any documentation page is available as raw Markdown by appending `.md` to its URL.

> Assemble a Temporal Proxy configuration for routing, Namespace translation, access control, credentials, and payload encryption.

> **Pre-release**
> Temporal Proxy is under active development and is not ready for production use. Behavior and configuration can change
> between releases. See the [temporal-proxy repository](https://github.com/temporalio/temporal-proxy) for current status
> and the definitive configuration schema.

Temporal Proxy reads one YAML configuration file at startup. Begin with a gateway listener, routing policy, and one or
more upstreams. Add inbound access controls, upstream TLS and credentials, and payload encryption according to the
deployment boundary you planned.

This page shows how the configuration fits together. Follow the linked task pages for the complete behavior and
options of each section.

## Assemble the configuration

The following configuration exposes a plaintext local endpoint and forwards namespaced and Namespace-less calls to a
local Temporal Service:

```yaml
hostPort: 127.0.0.1:7233

routing:
  default: local
  system: local

upstreams:
  - name: local
    hostPort: 127.0.0.1:8233
```

Build from that baseline in this order:

1. Define the gateway address with `hostPort` and, when callers cross an untrusted network, configure top-level `tls`.
2. Define each destination in `upstreams`, then select destinations with `routing`.
3. Add Namespace translation under an upstream's `namespaces` block when local and remote names differ.
4. Add an upstream `tls` block and `credentials` when the destination requires them.
5. Restrict inbound gRPC services with `allowedServices` and add `auth` when the gateway must authenticate or authorize
   callers.
6. Add `encryption` when the proxy must encrypt supported Payload fields before forwarding them.

The configuration areas map to separate operating jobs:

| Job | Configuration sections | Guide |
| --- | --- | --- |
| Select destinations and map Namespace names | `routing`, `upstreams[].hostPort`, `upstreams[].namespaces` | [Route requests and translate Namespaces](/production-deployment/temporal-proxy/route-translate) |
| Protect the gateway and upstream connections | `tls`, `allowedServices`, `auth`, `upstreams[].tls`, `upstreams[].credentials`, `extensionServers` | [Secure connections and authorize requests](/production-deployment/temporal-proxy/secure-connections) |
| Encrypt Payloads | `encryption`, optional KMS `extensionServers` | [Encrypt Payloads](/production-deployment/temporal-proxy/encrypt-payloads) |
| Rotate and retire encryption keys | `encryption.default`, `encryption.overrides`, `decryptURIs` | [Manage encryption keys](/production-deployment/temporal-proxy/manage-encryption-keys) |
| Mount configuration and secrets with Helm | Chart `config`, `env`, `envFrom`, and Secret references | [Deploy Temporal Proxy to Kubernetes](/production-deployment/temporal-proxy/deploy-kubernetes) |

See the [Temporal Proxy reference](/production-deployment/temporal-proxy/reference) for the top-level key map and the
source of truth for the complete schema.

## Supply environment-specific values

Configuration string values support environment variable expansion in either `${VAR}` or `$VAR` form. Keep secrets
out of the YAML file and resolve them from the process environment:

```yaml
upstreams:
  - name: cloud
    hostPort: ${TEMPORAL_NAMESPACE}.${TEMPORAL_ACCOUNT}.tmprl.cloud:7233
    tls: {}
    credentials:
      static:
        apiKey: ${TEMPORAL_API_KEY}
```

Undefined environment variables expand to an empty string, so verify that every required variable is present before
starting the proxy. On Kubernetes, use the chart's Secret integration instead of putting a credential in a ConfigMap.
See [Supply credentials from a Secret](/production-deployment/temporal-proxy/deploy-kubernetes#supply-credentials-from-a-secret).

An upstream `hostPort` and `tls.serverName` can also use Go templates that the proxy resolves for each request. For
example, the Temporal Cloud configuration can derive the endpoint from the translated Namespace:

```yaml
upstreams:
  - name: cloud
    hostPort: '{{ .RemoteNamespace }}.tmprl.cloud:7233'
    tls: {}
```

Available template values and routing order are documented in
[Route requests and translate Namespaces](/production-deployment/temporal-proxy/route-translate).

## Start with the configuration

Pass the configuration path to `proxy serve`:

```bash
proxy serve --config config.yaml
```

The `--config` flag also reads the `PROXY_CONFIG` environment variable. The proxy validates references and supported
values while it starts and exits when it finds an invalid configuration. It reads configuration only at startup, so
restart every proxy instance after a change.

Before directing application traffic to a new configuration:

1. Start the proxy in an evaluation environment and resolve every startup error.
2. Check the gateway health service.
3. Connect a Client through the gateway and call both a Namespace-scoped operation and a Namespace-less operation.
4. Confirm the selected upstream, authentication result, and any encryption operations in logs and metrics.
5. Test direct upstream access when your design intends to prevent bypass.

See [Operate and troubleshoot Temporal Proxy](/production-deployment/temporal-proxy/operate-troubleshoot) for health
checks, diagnostics, metrics, and common failure modes.

## Continue configuring

- [Get started with Temporal Cloud](/production-deployment/temporal-proxy/get-started-cloud)
- [Plan a Temporal Proxy deployment](/production-deployment/temporal-proxy/plan-deployment)
- [Route requests and translate Namespaces](/production-deployment/temporal-proxy/route-translate)
- [Secure connections and authorize requests](/production-deployment/temporal-proxy/secure-connections)
- [Encrypt Payloads](/production-deployment/temporal-proxy/encrypt-payloads)