<!-- beta:temporal -->
# Temporal

Define managed Temporal workflow engines for durable workflows, background tasks, AI agents, cron jobs, batch jobs and more.

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 `temporal` block in `specific.hcl` and reference it from services:

```hcl
temporal "tasks" {}

build "app" {
  base = "node"
}

service "worker" {
  build   = build.app
  command = "node worker.js"

  env = {
    TEMPORAL_ADDRESS   = temporal.tasks.url
    TEMPORAL_NAMESPACE = temporal.tasks.namespace
    TEMPORAL_API_KEY   = temporal.tasks.api_key
  }

  dev {
    command = "node --watch worker.js"
  }
}
```

## Reference attributes

Each `temporal` block exposes the following reference attributes:

| Attribute | Description | Dev value |
|-----------|-------------|-----------|
| `temporal.<name>.url` | gRPC address of the Temporal server | `localhost:<port>` |
| `temporal.<name>.namespace` | Temporal namespace | `default` |
| `temporal.<name>.api_key` | API key for authentication | `""` (empty, no auth in dev) |

These attributes can be used in service `env` blocks, both as standalone values and inside interpolated strings.

## Development

Running `specific dev` automatically:

1. Downloads the Temporal CLI (first run only)
2. Starts a Temporal dev server with persistent storage
3. Makes the Temporal Web UI available in the admin sidebar under "Workflows"

Workflow data persists across dev server restarts using a SQLite database stored in `.specific/keys/<key>/data/`.

The `api_key` attribute returns an empty string in dev since the Temporal dev server does not require authentication. This is safe because Temporal SDKs conditionally apply authentication based on whether a non-empty key is provided.

## Production

Production Temporal support is not yet available through `temporal` blocks. For production, use configs and secrets to pass Temporal Cloud credentials directly:

```hcl
temporal "tasks" {}

config "temporal_address" {}
secret "temporal_api_key" {
  dev {
    required = false
  }
}

service "worker" {
  build   = build.app
  command = "node worker.js"

  env = {
    # Use built-in temporal block for dev
    TEMPORAL_NAMESPACE = temporal.tasks.namespace

    # Override address and API key for production via config/secret
    TEMPORAL_ADDRESS = config.temporal_address
    TEMPORAL_API_KEY = secret.temporal_api_key
  }

  dev {
    command = "node --watch worker.js"
    env = {
      # In dev, use the local Temporal server
      TEMPORAL_ADDRESS = temporal.tasks.url
      TEMPORAL_API_KEY = temporal.tasks.api_key
    }
  }
}
```

Set the production values with `specific secrets set` and environment config before deploying.
<!-- /beta:temporal -->
