# Temporal

Temporal is a durable workflow engine. This guide covers running Temporal locally during development and connecting to Temporal Cloud in production.

Temporal has extensive SDK support across many languages including TypeScript, Python, Go, Java, .NET, and PHP. See the [Temporal documentation](https://docs.temporal.io/) for language-specific guides on implementing workers, workflows, and activities. This document only covers integration with Specific.

## Configuration

Define a dev-only Temporal service that runs locally, along with configs and secrets for production Temporal Cloud.

```hcl
build "app" {
  base = "node"
}

# Dev-only service: runs local Temporal server during development
# No top-level command means it's excluded from production deployment
#
service "temporal" {
  endpoint "grpc" {}
  endpoint "ui" { public = true }

  dev {
    command = "temporal server start-dev --port $GRPC_PORT --ui-port $UI_PORT --db-filename /tmp/temporal.db"
    env = {
      GRPC_PORT = endpoint.grpc.port
      UI_PORT   = endpoint.ui.port
    }
  }
}

# Temporal Cloud address (e.g., your-namespace.tmprl.cloud:7233)
config "temporal_address" {}

# Namespace - uses "default" in dev, must be set for production
config "temporal_namespace" {
  dev {
    default = "default"
  }
}

# API key for Temporal Cloud - not required in dev
secret "temporal_api_key" {
  dev {
    required = false
  }
}

service "app" {
  build = build.app
  command = "node index.js"
  expose {}

  env = {
    PORT               = port
    TEMPORAL_ADDRESS   = config.temporal_address
    TEMPORAL_NAMESPACE = config.temporal_namespace
    TEMPORAL_API_KEY   = secret.temporal_api_key
  }

  dev {
    command = "node --watch index.js"
    env = {
      # Override to use local Temporal service instead
      TEMPORAL_ADDRESS = ""
      TEMPORAL_HOST    = service.temporal.endpoint.grpc.host
      TEMPORAL_PORT    = service.temporal.endpoint.grpc.port
    }
  }
}
```

## Development

Running `specific dev` automatically starts a local Temporal server. The user must install the Temporal CLI for this: https://temporal.io/setup/install-temporal-cli. The Temporal Web UI is available at the public endpoint URL shown in the output.

Your app connects to the local Temporal server using the service endpoint environment variables (`TEMPORAL_HOST` and `TEMPORAL_PORT`).

## Production

In production, the dev-only `temporal` service is excluded from deployment. Your app connects to Temporal Cloud using:

1. `temporal_address` - Your Temporal Cloud address (e.g., `your-namespace.tmprl.cloud:7233`)
2. `temporal_namespace` - Your Temporal Cloud namespace
3. `temporal_api_key` - API key for authentication

Set these with `specific secrets set` before deploying.

## SDK support
