The simplest way to run Temporal Cloud Proxy is as a native binary. The build requires Go 1.24 or later and produces a single self-contained executable (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.
tclp) with no runtime dependencies. Once built, you can run it on any compatible Linux or macOS host by pointing it at a YAML config file.
Prerequisites
- Go 1.24 or later — the proxy module and CI pipeline both target Go 1.24
- git — to clone the repository
- Access to Temporal Cloud — a namespace with either mTLS certificates or an API key
Build
Build with make
go build -o ./tclp ./cmd and places the binary at ./tclp in the repository root.Makefile Targets
| Target | Description |
|---|---|
make build | Compile the tclp binary to ./tclp |
make clean | Remove the compiled ./tclp binary |
make all | Run tests, then build (test + build) |
make test | Run all tests (go test ./...) |
make test-verbose | Run all tests with verbose output (-v) |
make test-coverage | Run all tests with coverage reporting (-cover) |
make test-race | Run all tests with the race detector (-race) |
make test-short | Run all tests in short mode (-short) |
make test-clean | Clear the Go test cache (go clean -testcache) |
make benchmark | Run all benchmarks (go test -bench=. ./...) |
make test-auth | Run tests for the auth package only |
make test-crypto | Run tests for the crypto package only |
make test-proxy | Run tests for the proxy package only |
make test-utils | Run tests for the utils package only |
CLI Flags
Thetclp binary accepts two flags:
Alias:
-cPath to the YAML configuration file. Defaults to config.yaml in the current working directory.Log level for structured output. Accepted values:
debug, info, warn, error. Defaults to info.Running
With aconfig.yaml present in the current directory, start the proxy with no extra flags:
host and port specified in the config (server.host / server.port) and exposes Prometheus metrics on metrics.port.
Graceful Shutdown
The proxy registers handlers for bothSIGTERM and SIGINT. When either signal is received, the main loop calls app.Stop(), which triggers the fx lifecycle shutdown hooks. Those hooks call transport.Stop(), which in turn calls grpc.GracefulStop() to drain in-flight requests before the process exits.
To stop the proxy gracefully:
Abrupt termination (e.g.
kill -9) bypasses graceful shutdown and may leave in-flight Temporal requests incomplete. Always prefer SIGTERM or SIGINT when stopping the proxy.systemd Service
To run the proxy as a managed service on a Linux host, create a systemd unit file:/etc/systemd/system/temporal-cloud-proxy.service, then enable and start it: