> ## Documentation Index
> Fetch the complete documentation index at: https://docs.resolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Temporal

The [Temporal](https://temporal.io/) integration gives Resolve AI read-only access to your workflows, activities, task queues, and schedules during alert investigations.

## How It Works

Resolve runs **read-only** [Temporal CLI](https://docs.temporal.io/cli) commands against your Temporal frontend over gRPC, and only read operations are permitted. Resolve runs these commands from the **[Resolve Satellite](/resolve-satellite)** in your environment, so the Satellite is required in every case below — what differs is how it authenticates to Temporal:

* **Temporal Cloud (API key)** — the Satellite connects to your Temporal Cloud namespace using an API key over TLS.
* **mTLS (client certificate)** — the Satellite presents a client certificate over TLS. Works for Temporal Cloud or self-hosted.
* **Self-hosted (no auth)** — the Satellite connects to your in-network Temporal frontend over plaintext gRPC.

Resolve can:

* List and describe workflows, task queues, schedules, and namespaces
* Show workflow event history
* Count workflows matching a query
* Get a running workflow's stack trace

<Info>
  Write operations (such as `terminate`, `cancel`, `signal`, `reset`, and `delete`) are currently not supported.
  If you wish to allow Resolve AI to take write actions on Temporal, please contact [help@resolve.ai](mailto:help@resolve.ai)
</Info>

## Connect Temporal

<Tabs>
  <Tab title="Temporal Cloud">
    The Satellite connects to Temporal Cloud over TLS using an API key you add to the Temporal connection.

    **Prerequisites:**

    * A **[Resolve Satellite](/resolve-satellite)** (`v1.1.35+`) installed in your environment, with network egress to your Temporal Cloud endpoint (for example `*.tmprl.cloud:7233`).
    * A **Temporal Cloud API key**. Create one in the Temporal Cloud UI or CLI — see [Temporal Cloud API keys](https://docs.temporal.io/cloud/api-keys). The key only needs read access to the namespaces you want Resolve to investigate.
    * Your **Temporal Cloud gRPC endpoint**, e.g. `<namespace>.<account>.tmprl.cloud:7233`.
    * The **namespaces** you want Resolve to access (Temporal Cloud namespaces are formatted `<namespace>.<account>`).

    <Info>
      Temporal Cloud connections are enabled per organization. Contact [help@resolve.ai](mailto:help@resolve.ai) to turn this on for your org.
    </Info>

    Add the integration to your Satellite configuration:

    ```yaml integrations.yaml theme={null}
    integrations:
      temporalIntegration:
        type: temporal
        create: true
        connection:
          address: <temporal-cloud-grpc-endpoint> # e.g. <namespace>.<account>.tmprl.cloud:7233
          namespaces:
            - <namespace>.<account> # the first entry is the default namespace
          apiKey: <temporal-cloud-api-key> # enables TLS + API-key authentication
    ```

    | Field        | Required    | Description                                                                |
    | ------------ | ----------- | -------------------------------------------------------------------------- |
    | `address`    | Yes         | Your Temporal Cloud gRPC endpoint.                                         |
    | `namespaces` | Yes (min 1) | Namespaces Resolve may target (`<namespace>.<account>`). First is default. |
    | `apiKey`     | Yes         | Temporal Cloud API key. Enables TLS and API-key authentication.            |

    The API key is stored encrypted and is only used to authenticate read-only queries. TLS is enabled automatically when an API key is present. Apply the updated configuration and restart the Resolve Satellite to pick up the new integration.
  </Tab>

  <Tab title="Self-hosted">
    For a self-hosted Temporal frontend, Resolve connects through the Satellite running in your environment.

    **Prerequisites:**

    * The **[Resolve Satellite](/resolve-satellite)** installed in the cluster (or network) that can reach your Temporal frontend.
    * The **Temporal frontend gRPC address**, resolvable from inside the Satellite (for example `temporal-frontend.temporal.svc.cluster.local:7233`).
    * The **namespaces** you want Resolve to access.

    No API key is required for self-hosted; the Satellite manages the connection. Add the integration to your Satellite configuration:

    ```yaml integrations.yaml theme={null}
    integrations:
      temporalIntegration:
        type: temporal
        create: true
        connection:
          address: <temporal-frontend-grpc-address> # e.g. temporal-frontend.temporal.svc.cluster.local:7233
          namespaces:
            - <namespace> # the first entry is the default namespace
            # - <another-namespace>                    # add more namespaces as needed
    ```

    | Field        | Required    | Description                                                                                |
    | ------------ | ----------- | ------------------------------------------------------------------------------------------ |
    | `address`    | Yes         | Temporal frontend gRPC address, resolvable from inside the Satellite's Kubernetes cluster. |
    | `namespaces` | Yes (min 1) | Namespaces Resolve may target. The first entry is treated as the default.                  |

    Apply the updated configuration and restart the Resolve Satellite to pick up the new integration.
  </Tab>

  <Tab title="mTLS (client certificate)">
    For a Temporal frontend that requires mutual TLS, the Satellite presents a client certificate over TLS. This works for both Temporal Cloud (certificate auth) and self-hosted Temporal. Do not also set an `apiKey` — API-key and mTLS auth are mutually exclusive.

    **Prerequisites:**

    * A **[Resolve Satellite](/resolve-satellite)** (`v1.1.36+`) installed in your environment, with network egress to your Temporal endpoint.
    * A **client certificate and private key** (PEM) issued from a Certificate Authority your Temporal frontend trusts. This pair is the credential; no API key is used.
    * The **server CA certificate** (PEM) if your Temporal serves a certificate from a private/custom CA.
    * Your **Temporal gRPC endpoint** and the **namespaces** you want Resolve to access.

    <Info>
      mTLS Temporal connections are enabled per organization. Contact [help@resolve.ai](mailto:help@resolve.ai) to turn this on for your org.
    </Info>

    Provide the client cert/key (and optional CA) to the Satellite, then point the connection at them with `remoteConfigKey`. Mounting the files from a secret is recommended so the private key stays on the Satellite; inline PEM (`httpAgentClientCert` / `httpAgentClientKey` / `httpAgentCertificate`) is also supported.

    ```yaml integrations.yaml theme={null}
    integrations:
      temporalIntegration:
        type: temporal
        create: true
        connection:
          address: <temporal-grpc-endpoint> # e.g. <namespace>.<account>.tmprl.cloud:7233
          namespaces:
            - <namespace> # the first entry is the default namespace
          remoteConfigKey: temporalIntegration # selects the client-cert config below
          tlsServerName: <server-name> # optional SNI override, if the cert name differs from the address host
        # Client certificate the Satellite presents to Temporal over mTLS. Mount these from a
        # secret (recommended); the private key never leaves the Satellite.
        httpAgentClientCertPath: /etc/secrets/temporal/client.crt
        httpAgentClientKeyPath: /etc/secrets/temporal/client.key
        httpAgentCertificatePath: /etc/secrets/temporal/ca.crt # server CA, only if Temporal uses a private CA
    ```

    | Field             | Required    | Description                                                                                       |
    | ----------------- | ----------- | ------------------------------------------------------------------------------------------------- |
    | `address`         | Yes         | Your Temporal gRPC endpoint.                                                                      |
    | `namespaces`      | Yes (min 1) | Namespaces Resolve may target. The first entry is treated as the default.                         |
    | `remoteConfigKey` | Yes         | Selects the Satellite client-cert config (`httpAgentClient*`) to present over mTLS.               |
    | `tlsServerName`   | No          | TLS server name (SNI) override, when the Temporal certificate name differs from the address host. |

    The client key is mounted on the Satellite and never sent to Resolve. TLS is enabled automatically when a client certificate is present. Apply the updated configuration and restart the Resolve Satellite to pick up the new integration.
  </Tab>
</Tabs>

## Verify the Connection

Resolve runs a two-step health check:

1. **Liveness** – confirms the Temporal CLI is available on the Satellite.
2. **Connectivity** – confirms the Satellite can reach Temporal (Cloud or self-hosted) for the first configured namespace, using whichever auth is configured (API key or client certificate).

Once both pass, the integration shows as healthy in the Resolve UI.

## Troubleshooting

| Symptom                                     | Likely Cause                                                                | Resolution                                                                                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication / connectivity fails (Cloud) | Invalid or expired API key, wrong endpoint, or no egress                    | Verify the Temporal Cloud API key, that `address` is your namespace's gRPC endpoint, and that the Satellite has egress to the Temporal Cloud endpoint |
| mTLS handshake fails                        | Wrong/expired client cert or key, or Temporal does not trust the issuing CA | Verify the client cert/key and that Temporal trusts the issuing CA; set `tlsServerName` if the certificate name differs from the address host         |
| Health check fails at the connectivity step | Satellite cannot reach the Temporal frontend                                | Verify `address` is correct and that network policies allow gRPC traffic from the Satellite                                                           |
| "Namespace not allowed" error               | A namespace was requested that isn't in your config                         | Add the namespace to the `namespaces` list                                                                                                            |
| "Only read-only commands allowed"           | A write operation was attempted                                             | Expected — the integration is read-only by design                                                                                                     |