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.

The repository includes a multi-stage Dockerfile that produces a minimal Alpine-based image. Pre-built images are published to GitHub Container Registry on every push to the main branch and on every tagged release, making it easy to pull a known-good image without building locally.

​
Image Registry

Images are published to ghcr.io/temporal-sa/temporal-cloud-proxy. The CI pipeline produces the following tags:
TagWhen published
latestEvery tagged release (e.g. v1.0.0)
<version>Tagged releases with the v prefix stripped (e.g. 1.0.0)
<git-sha>Every commit merged to the main branch

​
Quick Start

1

Pull the image

docker pull ghcr.io/temporal-sa/temporal-cloud-proxy:latest
2

Prepare your config file and certificates

Create a config.yaml on the host (see Configuration Overview for the full schema). If you are using mTLS authentication, also place your certificate and key files in a local certs/ directory so they can be bind-mounted into the container.
cp config.sample.yaml config.yaml
# Edit config.yaml with your namespace, auth, and workload settings
mkdir -p certs
3

Run the container

docker run -d \
  --name temporal-cloud-proxy \
  -p 7233:9000 \
  -p 9090:9090 \
  -v /path/to/config.yaml:/app/config/config.yaml \
  -v /path/to/certs:/app/certs \
  -e TEMPORAL_API_KEY=your-api-key \
  ghcr.io/temporal-sa/temporal-cloud-proxy:latest
This maps the container’s internal gRPC port 9000 to host port 7233 (the default port Temporal workers expect) and the Prometheus metrics port 9090 to the same port on the host.
The container’s internal gRPC port is 9000 (as declared by EXPOSE 9000 in the Dockerfile). Map it to whichever port your workers expect — typically 7233 for Temporal workloads.

​
Dockerfile Details

The image is built in two stages:
StageBase imagePurpose
buildergolang:1.24.1-alpineCompiles the tclp binary with CGO_ENABLED=0
Runtimealpine:3.19Runs the compiled binary in a minimal image
Key runtime image properties:
  • Non-root user: the process runs as appuser (uid 1001) in group appgroup (gid 1001)
  • Config path: the default entrypoint reads config from /app/config/config.yaml
  • Certs directory: /app/certs is created at image build time for certificate bind-mounts
  • Health check: nc -z localhost 9000 runs every 30 seconds (10s timeout, 5s start period, 3 retries)
  • Default entrypoint: ./tclp --config /app/config/config.yaml

​
Build Locally

If you want to build the image from source rather than pulling from the registry: 
docker build -t temporal-cloud-proxy:local .
Run your locally built image the same way as the pre-built image, substituting temporal-cloud-proxy:local for the ghcr.io reference: 
docker run -d \
  --name temporal-cloud-proxy \
  -p 7233:9000 \
  -p 9090:9090 \
  -v /path/to/config.yaml:/app/config/config.yaml \
  -v /path/to/certs:/app/certs \
  temporal-cloud-proxy:local

​
Docker Compose

For local development or simple deployments, a Docker Compose file is a convenient way to manage the proxy alongside other services: 
version: "3.8"
services:
  temporal-proxy:
    image: ghcr.io/temporal-sa/temporal-cloud-proxy:latest
    ports:
      - "7233:9000"
      - "9090:9090"
    volumes:
      - ./config.yaml:/app/config/config.yaml
      - ./certs:/app/certs
    environment:
      - TEMPORAL_API_KEY=${TEMPORAL_API_KEY}
    restart: unless-stopped
Start the stack with: 
TEMPORAL_API_KEY=your-key docker compose up -d
Store sensitive values like TEMPORAL_API_KEY in a .env file at the same level as your docker-compose.yml. Docker Compose automatically loads .env files, so you can keep credentials out of version control.

Build docs developers (and LLMs) love

Get started for freeTalk to us