Temporal Integration
Connect Temporal to enable the AI agent to run Temporal CLI commands against your cluster during investigations. The agent can list workflows, describe executions, inspect task queues, manage schedules, and more.
Capabilities
Once connected, the AI agent can run any temporal CLI command, including:
| Capability | Example Command |
|---|---|
| List Workflows | temporal workflow list --namespace prod |
| Describe Workflow | temporal workflow describe --workflow-id my-wf |
| Get Workflow History | temporal workflow show --workflow-id my-wf |
| Signal Workflow | temporal workflow signal --workflow-id my-wf --name my-signal |
| Cancel/Terminate Workflow | temporal workflow cancel --workflow-id my-wf |
| List Task Queues | temporal task-queue describe --task-queue my-queue |
| List Schedules | temporal schedule list --namespace prod |
| Describe Namespace | temporal operator namespace describe --namespace prod |
Prerequisites
- A Temporal cluster (Temporal Cloud or self-hosted)
- One of the supported authentication methods configured
- Namespace access
Setup
Go to Integrations in Autoheal and click Temporal.
Choose your authentication method from the dropdown:
- Cloud (API Key) — For Temporal Cloud with API key authentication
- Cloud (mTLS) — For Temporal Cloud with mutual TLS certificates
- Direct Connect — For any Temporal server by address, with optional mTLS
Fill in the required fields based on your selected auth method (see details below).
Enter a name for the integration (e.g., "Production Temporal") and click Save.
Authentication Methods
Cloud (API Key)
For Temporal Cloud clusters using API key authentication. This is the recommended method for Temporal Cloud.
| Field | Description | Example |
|---|---|---|
| Default Namespace | Your Temporal namespace | quickstart-vishal |
| Account ID | Your Temporal Cloud account ID | tukws |
| API Key | Temporal Cloud API key | tmprl_... |
The connection address is automatically derived as {namespace}.{account_id}.tmprl.cloud:7233.
Find your Account ID in your namespace URL: https://cloud.temporal.io/namespaces/{namespace}.{account_id}.
Generate an API key from an account-level Service Account in Temporal Cloud Settings to access all namespaces with a single integration.
Cloud (mTLS)
For Temporal Cloud clusters using mutual TLS certificate authentication.
| Field | Description |
|---|---|
| Default Namespace | Your Temporal namespace |
| Account ID | Your Temporal Cloud account ID |
| TLS Certificate | Client TLS certificate in PEM format |
| TLS Private Key | Client TLS private key in PEM format |
Your CA certificate must be uploaded to the Temporal Cloud namespace via the Temporal Cloud console before connecting with mTLS.
Direct Connect
For any Temporal server you can reach by address — on-prem, private cloud, BYOC, or any other deployment. Optionally provide TLS certificates if your server enforces mutual TLS.
| Field | Description | Example |
|---|---|---|
| Default Namespace | Your Temporal namespace | default |
| Temporal Host | Server address with port | temporal.internal:7233 |
| TLS Certificate | (Optional) Client TLS certificate in PEM format | |
| TLS Private Key | (Optional) Client TLS private key in PEM format | |
| Server CA Certificate | (Optional) Server CA cert in PEM format |
If your Temporal server does not require authentication, just provide the host — leave the TLS fields empty. If your server enforces mTLS, provide the client certificate and private key. The Server CA Certificate is only needed if your server uses a private CA not in the system trust store.
Multi-Namespace Support
The Default Namespace is used automatically for all commands. The agent can override it per-command using the --namespace flag:
List workflows in the staging namespace
The agent will run: temporal workflow list --namespace staging
For Temporal Cloud with API Key auth, a single integration can access all namespaces under the same account — just use an account-level Service Account API key.
Example Queries
Once connected, you can ask the AI agent questions like:
Show me all running workflows in the production namespace
What's the status of workflow payment-workflow-123?
Are there any stuck workflows? Check the task queue health.
List all schedules and check if any are paused
Show me the history of the last failed workflow
Required Permissions
| Permission | Why It's Needed |
|---|---|
| Namespace read | Access namespace information |
| Workflow read | View and list workflow executions |
| Task queue read | Monitor task queue status |
| Schedule read | Access scheduled workflows |
For security, create dedicated credentials for Autoheal with read-only permissions. Avoid using admin credentials.
Security Best Practices
- Use dedicated credentials: Create a separate API key or certificate pair for Autoheal
- Limit namespace access: Restrict access to only the namespaces needed
- Rotate credentials regularly: Update API keys and certificates on a regular schedule
- Prefer API Key for Cloud: API key auth is simpler and avoids certificate management overhead
Troubleshooting
Connection Refused
- Verify the host address and port are correct
- For Temporal Cloud, the address is auto-derived — check your Account ID and namespace are correct
- For self-hosted, ensure the cluster is accessible from Autoheal
- Verify network connectivity and firewall rules
Authentication Failed
- API Key: Verify the key is correct and not expired. Ensure it's from an account-level Service Account if accessing multiple namespaces.
- mTLS (Cloud): Ensure your CA certificate is uploaded to the namespace in the Temporal Cloud console
- mTLS (Direct Connect): Check that all certificates are in PEM format and not expired
Certificate Errors
- Ensure certificates are in PEM format (start with
-----BEGIN CERTIFICATE-----) - Check that the client key matches the client certificate
- For self-hosted, verify the Server CA certificate is the root CA that signed the server certificate
Namespace Not Found
- Verify the namespace name is correct (case-sensitive)
- For Temporal Cloud, use the namespace name shown in the console (not the full address)
- Check that the API key has access to the target namespace