Elsa Foundation

elsa-foundation is the transitional Elsa 4 foundation workspace.

It contains the Elsa backend and Studio in three product roots:

• Essentials/: backend libraries, tests and host applications.
• Extensions/<capability>/: optional backend implementations, tests and Studio components where present.
• Studio/: the Studio shell, shared UI, tests and frontend tooling.

Shared engineering documentation, tools and workflows remain at the root. Public Elsa 4 documentation source lives in website/docs/ and syncs to GitBook. Server and Studio retain independent builds and package identities.

These repositories develop the Elsa 4 preview. Elsa 3 uses the separate elsa-core and elsa-studio repositories.

• Try Elsa 4: run Workbench and Studio from published Docker images.
• Contribute to the server: follow the Elsa Foundation contribution guide.
• Contribute to Studio: follow the Elsa Foundation Studio contribution guide.

Screenshots

Elsa Studio running against Workbench from the published Docker images. Captured with Studio rev 7cb2f2c2; Write Line 4.0.5-preview, Flowchart 4.0.3-preview; the preview UI may change.

Designer	Completed run

See Your first workflow for the full walkthrough.

Philosophy

Elsa Foundation should be a thin protocol, not a fat one.

Its job is to define the narrow shared surface that lets modules cooperate: domain language, core contracts, extension points, invariants, and the quality gates needed to keep the system understandable. It should not become a platform-shaped dependency that every feature inherits by default.

Modules should stay opt-in. A shell composes only the capabilities it needs, and features such as persistence, HTTP, JavaScript, scheduling, and host-specific integrations should enter through explicit dependencies and composition. Keeping the foundation thin makes coupling visible, protects extension authors from choices they did not select, and keeps feature-workspace assets movable as Elsa continues the modular refactor.

Start here

• The process entry point is Essentials/apps/Elsa.Workbench/Program.cs; which features it composes is decided by Essentials/apps/Elsa.Workbench/shells.json.
• How a workflow executes traces one request from that entry point to a durable checkpoint, file by file.
• AGENTS.md is the provider-neutral entrypoint for AI agents and engineers.
• docs/README.md routes to glossary, skills, maps, reports, and architecture orientation.
• .specify/memory/constitution-framework.md and .specify/memory/constitution.md are the two-layer constitution and should be treated as quality gates, not as the primary learning path.

Repository role

This repo currently supports two roles:

• Feature development: shipping and testing Elsa foundation features through Speckit specs under specs/.
• Architecture development: reviewing, revising, and verifying the modular framework constitution and Elsa-specific architecture.

Feature-development workflows remain here for now, but the documentation and operating model are shaped so they can move to a future elsa-workspace repository with minimal churn.

Build

dotnet build Elsa.Server.slnx

For faster inner-loop work, open or build one of the committed developer solution filters. The full solution remains the completion gate.

To build and run the backend from source, check readiness, and execute a sample workflow, follow the backend source quickstart.

Supported management APIs

Management-client APIs are owned by their Elsa domains and can be composed directly by custom applications. Elsa.Workbench is a reference composition, not the implementation home of a server-wide management facade.

The canonical areas are Workflow Design, Activity Design, Expressions, Publishing, Runtime, and API Capabilities. An authenticated client loads one shell-relative GET /capabilities document, then follows the advertised domain links. Omitted domain features advertise no capability and expose no routes; endpoint-level action permissions remain authoritative.

See the domain-owned API specification, OpenAPI contract, and validation quickstart for composition and compatibility details.

Run with Docker

The fastest way to try the stack is to run the published images with Docker Compose, without cloning or building the repositories. That guide includes macOS/Linux and Windows PowerShell commands.

This starts Elsa.Workbench (http://localhost:13000) and Elsa Studio (http://localhost:14000) from the Docker Hub images elsaworkflows/elsa-workbench and elsaworkflows/elsa-studio (SQLite, ephemeral). The Docker quickstart covers this plus the build-from-source path with PostgreSQL, and explains the settings that wire Studio to the server backend (Studio__BackendBaseUrl, the Elsa host management key, CORS). For the full container/image reference (environment variables, mounts, persistence composition, troubleshooting), see docs/docker.md.