Create Nexus Namespace and Endpoint before running caller Workflow
Before executing a caller Workflow, create a Namespace for the caller using: temporal operator namespace create --namespace my-caller-namespace. Then create a Nexus Endpoint using: temporal operator nexus endpoint create --name my-nexus-endpoint-name --target-namespace default --target-task-queue my-task-queue. The Nexus Endpoint acts as a routing layer connecting the caller Namespace to the handler's target Namespace and Task Queue.
Example: Configure caller Workflow with Nexus Endpoint in registration
worker.registerWorkflowImplementationTypes(
WorkflowImplementationOptions.newBuilder()
.setNexusServiceOptions(
Collections.singletonMap(
"SayHelloNexusService",
NexusServiceOptions.newBuilder()
.setEndpoint("my-nexus-endpoint-name")
.build()))
.build(),
NexusCallerWorkflowImpl.class
);
This example shows registering a caller Workflow with WorkflowImplementationOptions that specify the Nexus Endpoint name for routing Nexus calls.
Example: Register Nexus Service Handler in Worker
Worker worker = factory.newWorker("my-task-queue");
worker.registerWorkflowImplementationTypes(SayHelloWorkflowImpl.class);
worker.registerActivitiesImplementations(new GreetActivitiesImpl());
worker.registerNexusServiceImplementation(new SayHelloNexusServiceImpl());
This example shows registering a Nexus Service implementation (SayHelloNexusServiceImpl) alongside Workflow and Activity implementations in the same Worker.
WorkflowClient configuration for caller Namespace
When creating a WorkflowClient for the caller side, pass WorkflowClientOptions.newBuilder().setNamespace("my-caller-namespace").build() to the WorkflowClient.newInstance() method. This ensures all Workflows executed by that client run in the caller Namespace.
Register Nexus Service Handlers in Worker using registerNexusServiceImplementation
A Worker must register Nexus Service Handlers using worker.registerNexusServiceImplementation() for the Worker to poll for and process incoming Nexus requests. This is the same Worker concept used for Workflows and Activities. The registerNexusServiceImplementation parameter receives an instance of the Nexus Service implementation.
Dev server setup for Standalone Nexus Operations
Start a local dev server with the Pre-release Temporal CLI using: ./temporal server start-dev --namespace my-caller-namespace --namespace my-handler-namespace. The Pre-release dev server enables Standalone Nexus Operations by default with no dynamic config required. The starter and Worker connect to two different Namespaces (a caller Namespace and a handler Namespace), mirroring how Nexus crosses Namespace boundaries.
Prerequisites for Temporal Nexus development
Prerequisites for working with Temporal Nexus in Python include: Temporal CLI version v1.3.0 or higher (recommended latest), and Temporal Python SDK version v1.14.1 or higher (recommended latest).
Start dev server for Standalone Nexus Operations with pre-created namespaces
Start the Pre-release dev server with caller and handler Namespaces pre-created using: ./temporal server start-dev --namespace my-caller-namespace --namespace my-handler-namespace. The starter and Worker connect to two different Namespaces (a caller Namespace and a handler Namespace), mirroring how Nexus crosses Namespace boundaries.
Standalone Nexus Operations require Pre-release Temporal CLI
Standalone Nexus Operations require a Pre-release build of the Temporal CLI. The standard brew install temporal build does not include Standalone Nexus Operation support during Pre-release.
Complete Python Nexus quickstart example - worker setup
To register Nexus Service handlers in worker.py:
```python
import asyncio
from temporalio.client import Client
from temporalio.worker import Worker
from workflows import SayHelloWorkflow
from activities import greet
from handler import SayHelloNexusServiceHandler
async def main():
client = await Client.connect("localhost:7233")
worker = Worker(
client,
task_queue="my-task-queue",
workflows=[SayHelloWorkflow],
activities=[greet],
nexus_service_handlers=[SayHelloNexusServiceHandler()],
)
print("Worker started.")
await worker.run()
if __name__ == "__main__":
asyncio.run(main())
```
Create Namespace for caller with temporal operator namespace create
Create a new Namespace for the caller using the command: temporal operator namespace create --namespace NAMESPACE_NAME. This provides isolation between the caller and handler sides.
Register Nexus Service handlers in Worker with nexusServices parameter
A Worker registers Nexus Service handlers using the nexusServices parameter when creating the Worker. This parameter accepts an array of service handlers. A Worker will only poll for and process incoming Nexus requests if Nexus Service Handlers are registered.
Create Nexus Endpoint to route requests between namespaces
A Nexus Endpoint is created using the temporal CLI command: temporal operator nexus endpoint create --name <endpoint-name> --target-namespace <namespace> --target-task-queue <task-queue>. The endpoint acts as a routing layer that connects a caller Namespace to the handler's target Namespace and Task Queue. The endpoint name must match the endpoint name used in the caller Workflow.
Create caller namespace with temporal CLI
Use the command 'temporal operator namespace create --namespace <namespace-name>' to create a new namespace for the caller side. Namespaces provide isolation between the caller and handler sides of Nexus.
TypeScript Nexus quickstart example: say-hello service
Complete working example showing a Nexus Service that wraps an existing Workflow. The service.ts defines a 'say-hello' service with a 'sayHello' operation taking MyInput (name: string) and returning string. The handler.ts implements WorkflowRunOperationHandler that starts the example workflow with the input name. The worker.ts registers the handler with nexusServices parameter. The workflows.ts callerWorkflow uses createNexusServiceClient() to invoke the operation. The caller-starter.ts runs the caller workflow in the my-caller-namespace.
Nexus endpoint create command flags and options
The temporal cloud nexus endpoint create command creates a new Nexus Endpoint on the Cloud Account. The endpoint name is used in workflow code to invoke Nexus operations. Required flags: --name (string, endpoint name to create), --target-namespace (string, namespace where handler worker polls for Nexus tasks), --target-task-queue (string, task queue where handler worker polls for Nexus tasks). Optional flags: --allow-namespace (string array, namespaces allowed to call this endpoint, can be specified multiple times), --api-key (string), --async (bool, return immediately after initiating operation), --async-operation-id (string, custom identifier for tracking async operation), --description (string, optional endpoint description in markdown), --description-file (string, path to file with endpoint description, mutually exclusive with --description), --idempotent (bool, succeed silently if resource already exists), --poll-interval (duration, time between status checks, max 10 minutes, supports m and s), --server (string, override Temporal Cloud API server address). Example: temporal cloud nexus endpoint create --name my-endpoint --target-namespace my-ns.my-account --target-task-queue my-tq
Nexus endpoint update command flags and options
The temporal cloud nexus endpoint update command updates an existing Nexus Endpoint on the Cloud Account. The endpoint is patched leaving existing fields for which flags are not provided unchanged. Must specify exactly one of: --name (string, endpoint name to update) or --id (string, endpoint ID to update). Optional flags: --api-key (string), --async (bool), --async-operation-id (string), --description (string, optional endpoint description in markdown), --description-file (string, path to file with endpoint description, mutually exclusive with --description), --idempotent (bool), --poll-interval (duration, max 10 minutes, supports m and s), --resource-version/-v (string, for optimistic concurrency control), --server (string), --target-namespace (string, namespace where handler worker polls), --target-task-queue (string, task queue where handler worker polls), --unset-description (bool, unset the endpoint description, cannot be used with --description or --description-file). Example: temporal cloud nexus endpoint update --name my-endpoint --target-namespace new-ns.my-account --target-task-queue new-tq
Nexus endpoint delete command flags and options
The temporal cloud nexus endpoint delete command deletes a Nexus Endpoint on the Cloud Account. Must specify exactly one of: --name (string, endpoint name to delete) or --id (string, endpoint ID to delete). Optional flags: --api-key (string), --async (bool, return immediately after initiating operation), --async-operation-id (string, custom identifier for tracking async operation), --idempotent (bool, succeed silently if resource already exists), --poll-interval (duration, time between status checks, max 10 minutes, supports m and s), --resource-version/-v (string, resource version for optimistic concurrency control, fetched automatically if not provided), --server (string, override Temporal Cloud API server address).
Nexus endpoint get command flags and options
The temporal cloud nexus endpoint get command retrieves a Nexus Endpoint configuration from the Cloud Account. Must specify exactly one of: --name (string, endpoint name to retrieve) or --id (string, endpoint ID to retrieve). Optional flags: --api-key (string, API key for authenticating with Temporal Cloud), --server (string, override Temporal Cloud API server address).
Nexus endpoint list command flags and options
The temporal cloud nexus endpoint list command lists Nexus Endpoint configurations on the Cloud Account. Optional flags: --api-key (string), --page-size (int, number of endpoints to return per page, defaults to 100, maximum 1000 endpoints can be fetched at a time), --page-token (string, token for retrieving next page of results, initial value is empty string), --server (string, override Temporal Cloud API server address).
Nexus endpoint allowed-namespace remove command flags and options
The temporal cloud nexus endpoint allowed-namespace remove command removes namespaces from the list of allowed callers of a Nexus Endpoint. Namespaces that are not currently allowed are silently ignored. Required flags: --name (string, name of Nexus Endpoint), --namespace (string array, namespace to remove, can be specified multiple times). Optional flags: --api-key (string), --async (bool, return immediately after initiating operation), --async-operation-id (string, custom identifier for tracking async operation), --idempotent (bool, succeed silently if resource already exists), --poll-interval (duration, max 10 minutes, supports m and s), --resource-version/-v (string, for optimistic concurrency control), --server (string, override Temporal Cloud API server address).
Global CLI flags for Temporal Cloud nexus commands
Global flags available with any temporal cloud nexus command: --api-key (string, no default, API key for authenticating with Temporal Cloud, can be used instead of interactive login for automation and CI/CD), --auto-confirm (bool, no default, automatically confirm prompts and actions requiring user confirmation, useful for scripting and automation), --config-dir (string, no default, directory path where CLI configuration files are stored including authentication tokens and settings), --disable-pop-up (bool, no default, prevent CLI from opening browser window during authentication, useful for headless environments), --server (string, default saas-api.tmprl.cloud:443, override Temporal Cloud API server address for connecting to non-production environments).
Nexus endpoint allowed-namespace commands: set and list
The temporal cloud nexus endpoint allowed-namespace command group manages which namespaces are allowed to call a Nexus Endpoint.
**Set Command**: The temporal cloud nexus endpoint allowed-namespace set command sets the full list of namespaces that are allowed to call a Nexus Endpoint, replacing any previously allowed namespaces.
Set Command Required Flags:
- --name (string): name of Nexus Endpoint
- --namespace (string array): namespace to allow, can be specified multiple times
Set Command Optional Flags:
- --api-key (string)
- --async (bool): return immediately after initiating operation
- --async-operation-id (string): custom identifier for tracking async operation
- --idempotent (bool): succeed silently if resource already exists
- --poll-interval (duration): time between status checks, max 10 minutes, supports m and s
- --resource-version/-v (string): for optimistic concurrency control, fetched automatically if not provided
- --server (string): override Temporal Cloud API server address
**List Command**: The temporal cloud nexus endpoint allowed-namespace list command lists all namespaces that are allowed to call a Nexus Endpoint.
List Command Required Flags:
- --name (string): name of Nexus Endpoint
List Command Optional Flags:
- --api-key (string): API key for authenticating with Temporal Cloud
- --server (string): override Temporal Cloud API server address