> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Nexus Inter-Workflow Communication

> Enable cross-namespace and cross-cluster workflow orchestration with Nexus RPC

## Overview

Nexus RPC is an open-source service framework for arbitrary-length operations whose lifetime may extend beyond a traditional RPC. It provides:

* **Cross-namespace communication** - Call workflows across namespace boundaries
* **Cross-cluster orchestration** - Coordinate workflows across Temporal clusters
* **Async operations** - Support for long-running operations with callbacks
* **Service abstraction** - Expose workflows as RPC services with defined contracts

<Note>
  Nexus is enabled by default in Temporal Server version 1.26.0 or newer. It is only supported in single-cluster setups (multi-cluster replication is not yet implemented).
</Note>

## Architecture

Nexus uses the [Nexus over HTTP Spec](https://github.com/nexus-rpc/api/blob/main/SPEC.md) implemented via the [Nexus Go SDK](https://github.com/nexus-rpc/sdk-go).

### HTTP Routes

The Frontend service exposes Nexus HTTP routes on the HTTP API port (default: `7243`):

<Accordion title="/namespaces/{namespace}/task-queues/{task_queue}/nexus-services">
  **Direct task queue dispatch** - Dispatch a Nexus task directly to a task queue.

  Used for namespace-local Nexus operations without endpoint registration.
</Accordion>

<Accordion title="/nexus/endpoints/{endpoint}/services">
  **Endpoint dispatch** - Dispatch a Nexus task to a registered endpoint by ID.

  Uses the Nexus endpoint registry for routing across namespaces/clusters.
</Accordion>

<Accordion title="/namespaces/{namespace}/nexus/callback">
  **Operation callbacks** - Complete a Nexus operation via callback.

  Callback URL for async operations to notify completion.
</Accordion>

## Configuration

<Steps>
  <Step title="Enable HTTP API">
    Ensure the HTTP API is enabled in your server configuration:

    ```yaml theme={null}
    services:
      frontend:
        rpc:
          httpPort: 7243
    ```

    This is enabled by default in standard Temporal configurations.
  </Step>

  <Step title="Configure Public URL">
    Set the public callback URL accessible to external callers:

    ```yaml theme={null}
    clusterMetadata:
      clusterInformation:
        {cluster_name}:
          enabled: true
          initialFailoverVersion: 1
          rpcAddress: "localhost:7233"
          httpAddress: "http://localhost:7243"  # Public HTTP URL
    ```

    Replace `{cluster_name}` with your cluster name.
  </Step>

  <Step title="Register Nexus Endpoints">
    Create Nexus endpoints to route operations:

    ```bash theme={null}
    # Using temporal CLI
    temporal operator nexus endpoint create \
      --name my-service \
      --target-namespace my-namespace \
      --target-task-queue my-task-queue
    ```
  </Step>
</Steps>

## Nexus Endpoints

Nexus endpoints define routing for operations:

### Endpoint Registry

Endpoints are stored in the `nexus_endpoints` table:

```sql theme={null}
CREATE TABLE nexus_endpoints (
    id BINARY(16) NOT NULL,
    data MEDIUMBLOB NOT NULL,
    data_encoding VARCHAR(16) NOT NULL,
    version BIGINT NOT NULL,
    PRIMARY KEY (id)
);
```

### Endpoint Configuration

<ParamField path="name" type="string" required>
  Human-readable endpoint name
</ParamField>

<ParamField path="target.namespace" type="string" required>
  Target namespace for operations
</ParamField>

<ParamField path="target.taskQueue" type="string" required>
  Task queue to dispatch operations to
</ParamField>

<ParamField path="description" type="string">
  Optional description of the endpoint's purpose
</ParamField>

## Operation Types

<Tabs>
  <Tab title="Sync Operations">
    Short-lived operations that complete within the RPC timeout:

    ```go theme={null}
    // Sync operation handler
    func (h *Handler) HandleSyncOperation(ctx context.Context, req *nexus.Request) (*nexus.Response, error) {
        // Process immediately
        result := processRequest(req.Payload)
        return &nexus.Response{Payload: result}, nil
    }
    ```

    * Completes within HTTP timeout
    * No operation ID required
    * Simple request-response pattern
  </Tab>

  <Tab title="Async Operations">
    Long-running operations that return an operation ID:

    ```go theme={null}
    // Async operation handler
    func (h *Handler) HandleAsyncOperation(ctx context.Context, req *nexus.Request) (*nexus.AsyncOperationHandle, error) {
        // Start workflow execution
        run, err := h.client.ExecuteWorkflow(ctx, options, workflowFunc, req.Payload)
        if err != nil {
            return nil, err
        }
        
        return &nexus.AsyncOperationHandle{
            OperationID: run.GetID(),
            CallbackURL: buildCallbackURL(run.GetID()),
        }, nil
    }
    ```

    * Returns operation ID immediately
    * Caller can poll for status
    * Supports completion callbacks
    * Can be cancelled
  </Tab>
</Tabs>

## Callbacks

Async operations support callbacks for completion notification:

```mermaid theme={null}
sequenceDiagram
    participant Caller
    participant NexusEndpoint
    participant Workflow
    participant CallbackURL

    Caller->>NexusEndpoint: Start async operation
    NexusEndpoint->>Workflow: Start workflow
    NexusEndpoint-->>Caller: Return operation ID + callback URL
    
    Workflow->>Workflow: Execute workflow logic
    
    Workflow->>CallbackURL: POST completion result
    CallbackURL->>Caller: Notify completion
```

### Callback URL Format

```
http://{httpAddress}/namespaces/{namespace}/nexus/callback
```

<Warning>
  Callback URLs must be accessible from the workflow execution environment. Ensure proper network configuration and firewall rules.
</Warning>

## Implementation in CHASM

Nexus is integrated with CHASM for workflow completion callbacks:

* **Location**: `components/nexusoperations/`
* **Callback handlers**: Process completion notifications from Nexus operations
* **State management**: Track operation status in workflow state
* **Error handling**: Retry failed callbacks with exponential backoff

See [CHASM Architecture](/architecture/chasm) for details on callback implementation.

## Security

Nexus endpoints support authentication and authorization:

<Steps>
  <Step title="TLS Configuration">
    Enable TLS for Nexus HTTP endpoints:

    ```yaml theme={null}
    services:
      frontend:
        rpc:
          http:
            tls:
              enabled: true
              certFile: /path/to/cert.pem
              keyFile: /path/to/key.pem
    ```
  </Step>

  <Step title="Authorization">
    Apply authorization rules to Nexus endpoints:

    ```yaml theme={null}
    global:
      authorization:
        jwtKeyProvider:
          keySourceURIs:
            - https://example.com/.well-known/jwks.json
    ```

    Nexus operations respect namespace-level authorization.
  </Step>
</Steps>

## Monitoring

Key metrics for Nexus operations:

* **nexus\_requests\_total** - Total Nexus requests received
* **nexus\_request\_latency** - Request processing latency
* **nexus\_callback\_attempts** - Callback delivery attempts
* **nexus\_callback\_failures** - Failed callback deliveries
* **nexus\_endpoint\_cache\_hits** - Endpoint registry cache hits

## Troubleshooting

<AccordionGroup>
  <Accordion title="Endpoint not found errors">
    **Symptoms**: 404 errors when calling Nexus endpoints

    **Solutions**:

    * Verify endpoint is registered: `temporal operator nexus endpoint list`
    * Check endpoint ID matches the request
    * Ensure endpoint cache has refreshed (may take up to 60 seconds)
  </Accordion>

  <Accordion title="Callback delivery failures">
    **Symptoms**: Operations complete but caller not notified

    **Solutions**:

    * Verify callback URL is accessible from workflow workers
    * Check network policies and firewall rules
    * Review callback retry metrics for transient failures
    * Ensure callback handler is responding with 2xx status
  </Accordion>

  <Accordion title="Cross-namespace permission denied">
    **Symptoms**: 403 errors when calling across namespaces

    **Solutions**:

    * Verify authorization rules allow cross-namespace access
    * Check JWT claims include required namespace permissions
    * Review authorization logs for denial reasons
  </Accordion>
</AccordionGroup>

## Limitations

<Warning>
  * **Single-cluster only** - Multi-cluster replication not yet supported
  * **Experimental API** - Routes may change before general availability
  * **No versioning** - Breaking changes to operations require endpoint coordination
</Warning>

## See Also

<CardGroup cols={2}>
  <Card title="CHASM Architecture" href="/architecture/chasm">
    Learn how Nexus integrates with CHASM components
  </Card>

  <Card title="Frontend Service" href="/architecture/frontend-service">
    Understand HTTP API implementation
  </Card>

  <Card title="Security" href="/operations/security">
    Configure authentication and authorization
  </Card>

  <Card title="Nexus Go SDK" icon="github" href="https://github.com/nexus-rpc/sdk-go">
    Official Nexus SDK documentation
  </Card>
</CardGroup>