Elsa Studio

A modern, component-based web studio for Elsa Workflows 3.x.

Design, run and operate workflows from the browser: a visual designer, live instance inspection, human tasks, secrets, diagnostics and more.

Overview

Elsa Studio is a standalone front end for the Elsa Workflows engine. It is a client-rendered application that talks directly to the Elsa REST API, so it can be deployed next to any Elsa server without changing the engine.

Three modules are always available: the dashboard, workflow definitions and workflow instances. Everything else is optional and switched on per deployment through configuration, and is hidden automatically when the connected backend does not have the matching feature installed.

Visual designer	Flowchart, sequence and state machine containers, a searchable quick-add palette, auto layout, live validation and keyboard-driven editing.
Operations	Instance viewer with the execution journal, activity state, incidents and variables, plus bulk cancel and retry through alterations.
Human tasks	A task inbox with assignment, dynamic forms, protected fields and completion outcomes.
Governance	Users, roles and permissions, labels, and write-only secrets that workflows reference by name.
Insight	A call-context view of how workflows invoke each other, data-flow overlays, console and structured logs.

Quick start

Prerequisites: Node.js 22 or newer, pnpm 10, and a running Elsa server with CORS open to the studio's origin.

pnpm install
pnpm dev                 # http://localhost:3000

Point servers[0].url in studio.config.json at your Elsa API, which is typically something like https://localhost:5001/elsa/api, then sign in. The default authentication provider is Elsa Identity, so a username and password is all you need.

New to the project? Start with the Getting started guide.

Documentation

Guide	What it covers
Getting started	Install, run, connect to a server, first sign-in.
Configuration	Adding servers, authentication providers, feature flags, theming, environment variables.
Modules	What every module does, how to enable it, and how to build a new one.
Designer	Containers, the quick-add palette, data flow, call context, keyboard shortcuts.
Deployment	Docker image, standalone output, runtime configuration.
Troubleshooting	CORS, hidden modules, sign-in failures, workflows from older Elsa versions.
Architecture	Module contract, data access, designer internals, conventions.

Screenshots

Dashboard

Throughput, status breakdown and per-workflow activity for the connected server.

Workflow definitions

Published and draft versions, labels, filtering and a column picker.

Call context

See where a workflow sits in the hierarchy: every workflow that calls it on the left, everything it calls on the right, with the call type on each edge, cycles highlighted, and unresolved or missing targets called out. Drill into any node to open that workflow.

Instance viewer

Replay a run against the diagram, with the journal, activity state, variables and incidents.

Human tasks

Task detail with instructions, form fields, protected values and the recorded outcome.

Completion renders the task's pinned form, validates required fields and submits the response back to the workflow.

Secrets

Credentials workflows reference by name. Values are write-only and never displayed.

Themes

Five palettes and light, dark or system appearance, selectable per user from the header.

Configuration at a glance

Configuration is resolved on the server for every request, so a container can be reconfigured without a rebuild. See Configuration for the full reference.

{
  "title": "Elsa Studio",
  "servers": [
    { "name": "Local", "url": "https://localhost:5001/elsa/api" },
    { "name": "Staging", "url": "https://staging.example.com/elsa/api", "tenantId": "tenant-1" }
  ],
  "auth": { "provider": "elsa-identity" },
  "features": {
    "environments": { "enabled": true },
    "labels": { "enabled": true },
    "secrets": { "enabled": true },
    "security": { "enabled": true },
    "alterations": { "enabled": true },
    "user-tasks": { "enabled": true },
    "settings": { "enabled": true },
    "appearance": { "enabled": true },
    "diagnostics-console-logs": { "enabled": true },
    "diagnostics-structured-logs": { "enabled": true }
  },
  "ui": { "defaultTheme": "system", "theme": "classic", "pollIntervalMs": 5000, "defaultPageSize": 25 }
}

Nothing in this document is secret: it is shipped to the browser.

Project layout

src/
  app/                      Next.js routes; the catch-all delegates to the module registry
  config/                   runtime configuration: zod schema, server loader, React provider
  lib/
    api/                    HTTP client, typed endpoint groups, TanStack Query provider
    auth/                   AuthStrategy contract and the five providers
    modules/                StudioModule contract, registry, route matcher
    permissions/            resource:verb permission set mirroring the server
  components/
    ui/                     shadcn components (generated)
    common/                 shared building blocks (DataTable, PageHeader, ConfirmProvider, …)
    shell/                  app shell, sidebar, header, login
  modules/                  one folder per feature module

Scripts

Command	Purpose
pnpm dev	Development server on port 3000.
pnpm build / pnpm start	Production build (standalone output) and server.
pnpm test	Unit tests (Vitest).
pnpm lint	ESLint.
npx tsc --noEmit	Type check.

Docker

docker build -t elsa-studio-react .
docker run -p 3000:3000 \
  -e STUDIO_SERVER_URL=https://elsa.example.com/elsa/api \
  -e STUDIO_FEATURES=labels,secrets,security \
  elsa-studio-react

Mount a studio.config.json at /app/studio.config.json, or pass the whole document in STUDIO_CONFIG, for the full configuration. See Deployment.