# 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 | Production value |
|-----------|-------------|-----------|------------------|
| `temporal.<name>.url` | gRPC address of the Temporal server | `localhost:<port>` | Temporal Cloud gRPC address |
| `temporal.<name>.namespace` | Temporal namespace | `default` | Managed namespace ID |
| `temporal.<name>.api_key` | API key for authentication | `""` (empty, no auth in dev) | Auto-generated API key |

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

Running `specific deploy` automatically provisions a managed [Temporal Cloud](https://temporal.io/cloud) namespace for each `temporal` block. No manual setup is required — the same configuration works in both dev and production:

1. A dedicated Temporal Cloud namespace is created
2. A service account with write access is provisioned
3. An API key is generated for authentication
4. Credentials are securely injected into your services

The reference attributes (`temporal.<name>.url`, `.namespace`, `.api_key`) resolve to the Temporal Cloud values in production, so no environment-specific overrides are needed.
