Temporal Cloud Proxy is a standard Go module requiring Go 1.24.1 or later. The build system produces a single binary namedDocumentation 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.
tclp with no external runtime dependencies — the binary embeds everything it needs and can be deployed as a standalone executable or packaged into a minimal container image.
Prerequisites
Go 1.24.1+
Install from go.dev/dl. Verify your version with
go version.Git
Required to clone the repository and for Go module resolution during the build.
Build Commands
The project ships aMakefile that covers the most common workflows. All targets write the compiled binary to ./tclp in the repository root.
make all runs the full test suite before compiling. Use it as a pre-commit sanity check to catch regressions before producing a new binary.Manual Go Build
You can invoke the Go toolchain directly if you prefer not to use Make:make build. The entry point is ./cmd/main.go, which bootstraps the Uber Fx dependency injection container and wires together all six modules before starting the gRPC server.
Cross-Compilation
The proxy is commonly deployed inside a Docker container or on a Linux server. Build a fully static Linux binary from any host OS using the standard Go cross-compilation environment variables:Setting
CGO_ENABLED=0 disables cgo and forces the linker to produce a fully static binary — no glibc dependency and no shared libraries. This matches the Dockerfile build and is required for deployment into scratch or distroless container images.CI/CD Pipeline
The repository includes a GitHub Actions workflow (.github/workflows/ci.yml) that runs automatically on every code change.
Triggers
The pipeline fires on:- Pushes to the
mainormasterbranch - Pull requests targeting
mainormaster - Version tags matching
v*.*.*
Jobs
test
Runs on The
ubuntu-latest. Sets up Go 1.24, then executes:build job only starts after test passes.build
Authenticates to GitHub Container Registry (
ghcr.io) and builds the Docker image.On pushes to main: builds linux/amd64 only and pushes a single image tagged with the commit SHA.On version tags (v*.*.*): builds both linux/amd64 and linux/arm64, then pushes three tags — latest, the bare version number (e.g. 1.2.3), and the commit SHA.Images are published to ghcr.io/temporal-sa/temporal-cloud-proxy.Key Dependencies
Thego.mod file declares the following major dependencies:
| Module | Purpose |
|---|---|
go.temporal.io/sdk | Temporal Go SDK — provides PayloadCodec, gRPC client interceptors, and the WorkflowServiceProxyServer factory |
go.temporal.io/api | Temporal API protobuf definitions, including WorkflowService used to register the proxy handler |
github.com/aws/aws-sdk-go | AWS SDK v1 — used by AWSKMSProvider to call GenerateDataKey and Decrypt |
cloud.google.com/go/kms | GCP Cloud KMS client — used by GCPKMSProvider to generate random bytes, encrypt, and decrypt data keys |
github.com/spiffe/go-spiffe/v2 | SPIFFE/SPIRE workload API client — used by SpiffeAuthenticator to connect to the SPIRE agent socket and validate JWT SVIDs |
github.com/golang-jwt/jwt/v4 + github.com/MicahParks/keyfunc | JWT parsing and JWKS key-set fetching with automatic background refresh — used by JwtAuthenticator |
go.uber.org/fx | Dependency injection framework that wires together all modules at startup |
go.uber.org/zap | Structured, levelled logging throughout the proxy |
google.golang.org/grpc | gRPC transport layer for both the inbound server and outbound Temporal Cloud connections |
github.com/prometheus/client_golang + go.opentelemetry.io/otel | Prometheus metrics registry and OpenTelemetry SDK for request counters, latency histograms, and KMS operation metrics |
github.com/hashicorp/golang-lru | Thread-safe LRU cache used by CachingMaterialsManager to avoid redundant KMS calls |