Skip to content
Hermes SwitchUI

Workflow Engine

Workflow Engine

The Workflow Engine is a Hermes Agent (Python gateway) plugin that ships as part of the Hermes Switch UI package. It is the backend that powers the Switch UI Workflows page when you set the backend toggle to plugin. The plugin exposes a REST API and five agent tools that let you define, trigger, monitor, approve, and cancel multi-step workflows — all running server-side inside the gateway process.

[SCREENSHOT: Switch UI Workflows page with the backend set to “plugin”, showing a running DAG workflow with phase progress]

What a workflow is

At the engine level, a workflow is a YAML file that describes a directed acyclic graph (DAG) of nodes. Each node is a discrete unit of work — a shell command, a Python or TypeScript script, a prompt sent to an AI agent, a Hermes Agent command, a human approval gate, or an embedded subgraph referencing another workflow. Edges between nodes declare dependencies: a node only executes after every node pointing to it has completed.

A minimal workflow skeleton looks like this:

name: my-workflow
description: What this workflow does and when to use it.
provider: claude
model: sonnet


nodes:
  - id: first-step
    phase: Discover
    bash: |
      echo "hello from step one"


  - id: second-step
    phase: Build
    depends_on: [first-step]
    hermes_task:
      agent_hint: neo
      model_hint: claude-sonnet-4
      skills: [coding]
    prompt: |
      Read the output of the previous step and summarise it.

The provider, model, and hermes_task fields let you route individual nodes to different models or specialised agents. Nodes that share no dependencies run in parallel automatically.

Bundled workflows

The plugin ships more than twenty ready-to-use workflow definitions under its defaults/ directory. These cover common engineering tasks such as fixing a GitHub issue, creating a PR from a plan, running a comprehensive code review, scaffolding a PRD through a guided conversation, and refactoring a codebase safely. Bundled workflows are read-only — you can run and copy them, but you cannot edit or delete them from Switch UI.

When a bundled workflow’s YAML changes in a new release, its checksum updates and Switch UI highlights the change so you know an update is available.

Cron-triggered runs

Workflows can include a cron field containing a standard five-field cron expression. When the plugin’s background daemon is running, it polls for due cron schedules and launches runs automatically:

name: nightly-digest
cron: "0 2 * * *"
nodes:
  - id: build-digest
    bash: ./scripts/build-digest.sh

The daemon is a separate process from the gateway request loop. You start it with:

Terminal window
hermes workflow daemon --interval 60

The --interval value (in seconds) controls how often the daemon wakes to check for due cron jobs, pending Kanban tasks, and scheduled ticks. The daemon handles SIGINT and SIGTERM for clean shutdown; in production you should supervise it with systemd, launchd, or a similar process manager.

Where workflows are defined

When the plugin backend is active, workflow definitions are stored in a SQLite database managed by the plugin — separate from the native backend’s store. You can register a new workflow by uploading its YAML through the Switch UI Workflows page or via the plugin REST API. The allowed_roots config key controls which filesystem paths are trusted as workflow file sources:

workflow:
  allowed_roots: ["~", "${HERMES_HOME}"]
  run_rate_per_session: 5
  approve_any: false

run_rate_per_session limits how many runs a single session can start to prevent runaway automation. approve_any controls whether any user may approve an approval-type node or only the session owner.

How it relates to the Switch UI Workflows page

Switch UI ships two workflow engine backends. By default it uses the native TypeScript engine embedded in the Switch UI server — no gateway required. When you switch to the plugin backend in Settings → Workflows → Backend, every workflow API call is proxied through to this plugin running inside the hermes-agent gateway.

The plugin backend adds two capabilities the native backend does not have: cron-triggered runs and Kanban dispatcher integration (routing hermes_task nodes to named agents via the Kanban system). Everything else — SSE event streaming, approval gates, parallel node execution, phase grouping — works identically in both backends.

Definitions are not shared between backends. If you switch, you will need to re-register your workflows in the target store. See Workflows backend toggle for migration steps and a full feature comparison table.

Enabling the plugin

The plugin must be enabled in the Hermes Agent gateway before Switch UI can use it:

Terminal window
hermes plugins enable workflow-engine
hermes dashboard restart

After restarting, verify the routes are live:

Terminal window
curl http://localhost:8642/api/plugins/workflow-engine/definitions

Then open Settings → Workflows → Backend in Switch UI and select plugin.

[SCREENSHOT: Settings → Workflows → Backend toggle showing “plugin” selected with a green connected indicator]