Skip to main content

​
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
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).

​
Architecture

Nexus uses the Nexus over HTTP Spec implemented via the Nexus Go SDK.

​
HTTP Routes

The Frontend service exposes Nexus HTTP routes on the HTTP API port (default: 7243):
Direct task queue dispatch - Dispatch a Nexus task directly to a task queue.Used for namespace-local Nexus operations without endpoint registration.
Endpoint dispatch - Dispatch a Nexus task to a registered endpoint by ID.Uses the Nexus endpoint registry for routing across namespaces/clusters.
Operation callbacks - Complete a Nexus operation via callback.Callback URL for async operations to notify completion.

​
Configuration

1

Enable HTTP API

Ensure the HTTP API is enabled in your server configuration:
services:
  frontend:
    rpc:
      httpPort: 7243
This is enabled by default in standard Temporal configurations.
2

Configure Public URL

Set the public callback URL accessible to external callers:
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.
3

Register Nexus Endpoints

Create Nexus endpoints to route operations:
# Using temporal CLI
temporal operator nexus endpoint create \
  --name my-service \
  --target-namespace my-namespace \
  --target-task-queue my-task-queue

​
Nexus Endpoints

Nexus endpoints define routing for operations:

​
Endpoint Registry

Endpoints are stored in the nexus_endpoints table: 
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

​
name
string
required
Human-readable endpoint name
​
target.namespace
string
required
Target namespace for operations
​
target.taskQueue
string
required
Task queue to dispatch operations to
​
description
string
Optional description of the endpoint’s purpose

​
Operation Types

Short-lived operations that complete within the RPC timeout:
// 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

​
Callbacks

Async operations support callbacks for completion notification:

​
Callback URL Format

http://{httpAddress}/namespaces/{namespace}/nexus/callback
Callback URLs must be accessible from the workflow execution environment. Ensure proper network configuration and firewall rules.

​
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 for details on callback implementation.

​
Security

Nexus endpoints support authentication and authorization:
1

TLS Configuration

Enable TLS for Nexus HTTP endpoints:
services:
  frontend:
    rpc:
      http:
        tls:
          enabled: true
          certFile: /path/to/cert.pem
          keyFile: /path/to/key.pem
2

Authorization

Apply authorization rules to Nexus endpoints:
global:
  authorization:
    jwtKeyProvider:
      keySourceURIs:
        - https://example.com/.well-known/jwks.json
Nexus operations respect namespace-level authorization.

​
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

Symptoms: 404 errors when calling Nexus endpointsSolutions:
  • 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)
Symptoms: Operations complete but caller not notifiedSolutions:
  • 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
Symptoms: 403 errors when calling across namespacesSolutions:
  • Verify authorization rules allow cross-namespace access
  • Check JWT claims include required namespace permissions
  • Review authorization logs for denial reasons

​
Limitations

  • 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

​
See Also

CHASM Architecture

Learn how Nexus integrates with CHASM components

Frontend Service

Understand HTTP API implementation

Security

Configure authentication and authorization

Nexus Go SDK

Official Nexus SDK documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us