Temporal workflows on Catalyst

Catalyst can run workflows written with the Temporal SDKs. You keep your workflow and activity code, your workers and your clients. You point them at Catalyst instead of a Temporal server, and Catalyst runs the workflows and stores their history.

Preview

Temporal workflows on Catalyst are in preview. Features and behavior can change before general availability, and not every region supports them yet.

How it works

• A Catalyst App is your Temporal namespace. You create an App that uses the Temporal workflow API. Its name is the namespace your workers and clients use.
• Your code talks to Catalyst with the Temporal SDK. Workers poll Catalyst for tasks and clients start, signal, query and update workflows, as they would with a Temporal server.
• Catalyst runs the server side. There's no Temporal server, database or visibility store to run.
• You see your workflows in Catalyst. Temporal workflows appear in the workflows view of the Catalyst console, with their history.

Catalyst is tested with the Temporal Go, Java, Python and TypeScript SDKs, and with the Temporal CLI.

Set up a Temporal App

You need the Diagrid CLI, logged in with diagrid login. On macOS and Linux you also need jq.

1. Create a project and an App

Create a project with managed workflows, then an App that uses the Temporal workflow API:

diagrid project create my-project --enable-managed-workflow --use
diagrid app create orders --workflow-api temporal --wait

You choose the workflow API when you create the App, and you can't change it later. If your region doesn't support Temporal workflows yet, diagrid app create says so.

2. Set Temporal's connection settings

Temporal's SDKs and CLI read their connection settings from environment variables. Set them to your project's endpoint, the App's name and the App's API token:

macOS/Linux

export TEMPORAL_ADDRESS="$(diagrid project get my-project -o json | jq -r '.status.endpoints.grpc | "\(.host):\(.port)"')"
export TEMPORAL_NAMESPACE=orders
export TEMPORAL_API_KEY="$(diagrid appid get orders -o json | jq -r .status.apiToken)"

Windows

$grpc = (diagrid project get my-project -o json | ConvertFrom-Json).status.endpoints.grpc
$env:TEMPORAL_ADDRESS = "$($grpc.host):$($grpc.port)"
$env:TEMPORAL_NAMESPACE = "orders"
$env:TEMPORAL_API_KEY = (diagrid appid get orders -o json | ConvertFrom-Json).status.apiToken

Catalyst only accepts encrypted connections. Temporal's SDKs and CLI turn on TLS when an API key is set, so you don't need another setting.

3. Run your workers and clients

Start your worker and your client as you usually do. Your workflows now run on Catalyst.

Check on them with the Temporal CLI, which reads the same settings:

temporal workflow list

You can also use diagrid workflow list or the Catalyst console.

If your code sets the connection itself

Code that loads Temporal's environment configuration needs no changes. Temporal's money transfer tutorials do this.

If your code passes a fixed address such as localhost:7233, load the environment configuration instead:

Python

from temporalio.client import Client
from temporalio.envconfig import ClientConfig

client = await Client.connect(**ClientConfig.load_client_connect_config())

Go

import (
	"go.temporal.io/sdk/client"
	"go.temporal.io/sdk/contrib/envconfig"
)

c, err := client.Dial(envconfig.MustLoadDefaultClientOptions())

The Java and TypeScript SDKs have the same environment configuration. You can also pass the address, namespace and API key to the client yourself, with TLS turned on.

Next steps

Run Temporal's quickstart

Run Temporal's money transfer sample on Catalyst without changing its code.

Temporal compatibility

What's supported, what isn't available yet, and where Catalyst behaves differently from a Temporal server.