temporal-ts-net

Extension command for Temporal CLI that runs the Temporal development server and exposes it on your Tailscale tailnet.

This extension provides:

• temporal ts-net - wraps temporal server start-dev with Tailscale networking
• Automatic exposure of your dev server across your tailnet
• Simple setup with automatic Tailscale authentication
• Connection limiting and rate limiting for production-like constraints

Install

Build the extension binary:

# Using mage (if installed)
mage build

# Using go run (no mage installation required)
go run mage.go build

# Or directly with go
go build -o ./bin/temporal-ts_net ./cmd/temporal-ts_net

Add ./bin to your PATH and verify discovery:

temporal help --all

You should see ts-net listed as an extension command.

Usage

Start dev server on your Tailscale tailnet:

temporal ts-net

This starts temporal server start-dev locally and exposes it on your tailnet at temporal-dev:7233.

Customize the hostname:

temporal ts-net --tailscale-hostname my-temporal

Pass any temporal server start-dev flags through directly:

temporal ts-net \
    --tailscale-hostname my-temporal \
    --port 7234 \
    --ui-port 8234 \
    --db-filename /tmp/temporal-dev.db

Extension flags

• --tailscale-hostname / --tsnet-hostname: Tailnet hostname (default: temporal-dev)
• --tailscale-authkey / --tsnet-authkey: Auth key for non-interactive auth (or set TS_AUTHKEY env var)
• --tailscale-state-dir / --tsnet-state-dir: Local state directory for tsnet node
• --max-connections: Maximum concurrent connections (default: 1000)
• --connection-rate-limit: Maximum connections per second (default: 100)
• --dial-timeout: Timeout for dialing backend (default: 10s)
• --idle-timeout: Idle timeout for connections (default: 5m)

All other flags are forwarded to temporal server start-dev.

Testing

Running Tests

All tests (including Tailscale):

go test ./...

Tailscale tests run entirely in-process using testcontrol - no external services or auth keys needed!

Verbose output:

go test ./internal/tailscale -v

Demo

See the demo directory for a self-contained example of the Tailscale proxy pattern:

go run demo/tailscale-proxy/main.go

This demonstrates the complete proxy flow used by temporal ts-net --tailscale, running entirely in-process with no external dependencies.

CI Testing

Tailscale tests run automatically in CI with no configuration needed. They use testcontrol for isolated, reproducible testing.

Development

This project uses Mage for build tasks. You can use mage directly or via go run (zero-install):

# List all available targets
mage -l
# or (no mage installation required)
go run mage.go -l

# Available targets:
go run mage.go build    # Build the binary
go run mage.go test     # Run tests
go run mage.go fmt      # Format code
go run mage.go clean    # Remove build artifacts
go run mage.go install  # Install to $GOPATH/bin

Releases

This project uses GoReleaser with GitHub Actions to automate releases.

To create a new release:

# Tag the commit
git tag -a v0.1.0 -m "Release v0.1.0"

# Push the tag
git push origin v0.1.0

GitHub Actions will automatically:

• Build binaries for Linux, macOS, and Windows (amd64 and arm64)
• Create a GitHub release with changelog
• Upload release artifacts and checksums

Download pre-built binaries from the Releases page.