Cadence Web UI

April 7, 2026 · View on GitHub

Cadence is a distributed, scalable, durable, and highly available orchestration engine we developed at Uber Engineering to execute asynchronous long-running business logic in a scalable and resilient way.

This web UI is used to view workflows from Cadence, see what's running, and explore and debug workflow executions.

Getting Started

Using cadence-web

The latest version of cadence-web is included in the cadence composed docker containers in the main Cadence repository. Follow the instructions there to get started.

docker-compose -f docker/docker-compose.yml up

Configuration

Set these environment variables if you need to change their defaults.

Variable	Description	Default
CADENCE_GRPC_PEERS	Comma-delimited list of gRPC peers	127.0.0.1:7833
CADENCE_GRPC_SERVICES_NAMES	Comma-delimited list of gRPC services to call	cadence-frontend
CADENCE_CLUSTERS_NAMES	Comma-delimited list of cluster names	cluster0
CADENCE_WEB_PORT	HTTP port to serve on	8088
CADENCE_WEB_HOSTNAME	Host name to serve on	0.0.0.0
CADENCE_ADMIN_SECURITY_TOKEN	Admin token for accessing admin methods	''
CADENCE_WEB_AUTH_STRATEGY	Auth strategy resolver. Supported values: `disabled` or `jwt`; invalid or unset values fall back to `disabled`.	disabled
CADENCE_GRPC_TLS_CA_FILE	Path to root CA certificate file for enabling one-way TLS on gRPC connections	''
CADENCE_WEB_SERVICE_NAME	Name of the web service used as GRPC caller and OTEL resource name	cadence-web

Note: To connect cadence-web to multiple clusters, you will need to add comma-delimted entries for CADENCE_GRPC_PEERS, CADENCE_GRPC_SERVICES_NAMES & CADENCE_CLUSTERS_NAMES for each cluster (each cluster values are grouped by their index within the Comma-delimited lists).

Example:

CADENCE_GRPC_PEERS=127.0.0.1:3000,127.0.0.1:5000 
CADENCE_GRPC_SERVICES_NAMES=cadence-frontend-cluster0,cadence-frontend-cluster1
CADENCE_CLUSTERS_NAMES=cluster0,cluster1

CADENCE_WEB_AUTH_STRATEGY is resolved server-side to one of the supported auth strategies: disabled or jwt. Invalid or unset values fall back to disabled.

When the resolved strategy is jwt, cadence-web authenticates using a cookie:

Cookie name: cadence-authorization
Cookie value: raw JWT string

To integrate an upstream proxy / IdP, set the cookie for the cadence-web origin:

Set-Cookie: cadence-authorization=<JWT>; Path=/; HttpOnly; SameSite=Lax; Secure

You can also set/clear the cookie via POST /api/auth/token and DELETE /api/auth/token; or use Login with JWT button in the UI.

Feature flags

Feature flags control various UI features and functionality in cadence-web. These can be configured using environment variables.

Feature	Description	Environment Variable Configuration	Minimum Cadence Server Version
Extended Domain Information	Enhanced domain metadata display and help menu UI	`CADENCE_EXTENDED_DOMAIN_INFO_METADATA_ENABLED=true`	N/A
Workflow Diagnostics	Workflow diagnostics APIs and UI for debugging workflows	`CADENCE_WORKFLOW_DIAGNOSTICS_ENABLED=true`	1.2.13+ (1.3.1+ for full functionality)
Default Archival Search	Shows the default workflow search input and query input for archival workflows page. Default search is disabled by default as it doesn't work well with S3 implementation	`CADENCE_ARCHIVAL_DEFAULT_SEARCH_ENABLED=true`	N/A
Failover History List	List and filter domain failovers	`CADENCE_FAILOVER_HISTORY_ENABLED=true`	1.4.0+
New Workflow History View	New and improved UI for viewing workflow history	`CADENCE_HISTORY_PAGE_V2_ENABLED=ENABLED` (or `OPT_IN`/`OPT_OUT`)	N/A

Note: For advanced customization, feature flags can be modified through resolvers in the dynamic config system (src/config/dynamic/resolvers).

Using TLS for gRPC

You can run cadence-web with secure gRPC TLS communication by passing your CA certificate file to the container and configure the environment variable accordingly.

Steps to Pass the Certificate File in Docker

Prepare your CA certificate file:
Ensure you have the root CA file (e.g., ca.pem) accessible on your host machine.
Mount the certificate file into the container:
Use Docker volume mounting (-v or --volume) to make the certificate file available inside the container at a known path.
Set the CADENCE_GRPC_TLS_CA_FILE environment variable to the mounted certificate path:

Example command (for Linux):

docker run -it --rm \
  -p 8088:8088  \
  -v /path/on/host/ca.pem:/etc/certs/ca.pem:ro \
  -e CADENCE_GRPC_TLS_CA_FILE=/etc/certs/ca.pem \
  ubercadence/server:master-auto-setup

Replace /path/on/host/ca.pem with the actual location of your CA certificate on the host system.
CADENCE_GRPC_TLS_CA_FILE must point to the path inside the container where the certificate is mounted.

Building & developing cadence-web

cadence-web requires node v18 or greater to be able to run correctly.

Creating a production build

To create a production build, follow these steps:

Install npm packages and download idls

npm install && npm run install-idl && npm run generate:idl

Build the project files

npm run build

After building the code, start the server by running this command from the same directory as the build

npm start

Once the webapp is ready, access it through localhost:8088 (port can be changed using CADENCE_WEB_PORT environment variable)

Running development environment

To run the development server, follow these steps:

Install npm packages and download idls

npm install && npm run install-idl && npm run generate:idl

Run the development server using

npm run dev

Once the webapp is ready, access it through localhost:8088 (port can be changed using CADENCE_WEB_PORT environment variable)

Note: For contribution we recommend using dev containers, check VSCode Dev Containers for more information

Using VSCode Dev Containers

Set up the Remote Containers plugin in VSCode.
Open the cadence-web directory in VSCode.
Make sure to update CADENCE_GRPC_PEERS with the correct host. (If you are connecting to a server on a container host machine use host.docker.internal:7833, where 7833 is the gRPC port for a running cadence-frontend service)
Use the Command Palette to select the 'Reopen folder in Container' option
Follow the same commands listed in Running development environment.

Developing cadence-web against cadence composed docker

To start development against dockerized cadence services, run the following command from the root of the project

docker-compose -f docker-compose-backend-services.yml up

You can customize the YAML file or reuse configurations from the cadence repository. (In case of reusing existing files: ensure that cadence-web is not included in the composed container services, or just remove it)

After running cadence, start cadence-web for development using one of the previous methods (Running development environment, VSCode Dev Containers)

Updating IDLs

To update the Cadence IDL files:

Update the commit hash in package.json under config.cadence_idl_version to the latest commit hash from the cadence-idl repository.
Download the new IDL files:

npm run install-idl

Generate TypeScript types from the IDL files:

npm run generate:idl

Check for errors:

npm run lint && npm run typecheck && npm run test

Run cadence-web locally to sanity-check if everything works as expected (see Running development environment)
Fix any errors that arise from the updated IDL files.

NPM scripts

script	Description
build	Generate a production build
start	Start server for existing production build
dev	Run a development server
install-idl	Download idl files required for building/running the project
generate:idl	Move idl files inside the project and generate typescript types for them
test	Run all test cases. To pass extra jest flags, use environment specific scripts e.g. test:unit:*
test:unit	Run all unit tests. To pass extra jest flags, use environment specific scripts e.g. test:unit:*
test:unit:browser	Run only browser unit tests
test:unit:node	Run only node unit tests
lint	Run eslint
typecheck	Run typescript checks

Contributing

We'd love your help in making the Cadence Web UI great. Please review our contribution guidelines.

If you'd like to propose a new feature or discuss issues, join the CNCF Slack workspace in the #cadence-users channel to start a discussion.

License

Apache 2.0 License, please see LICENSE for details.