Workflows — saved automations
A workflow is a saved automation: something starts it (a message, a GitLab event, a time of day, or you), and then one or more steps run, such as asking an agent to do a job. Each time it starts is called a run.
You see your workflows in two places:
- Workflows on the Hub: every workflow with its state and last runs, a switch to turn it on or off, and a button to start it. Start here.
- The workflow editor, also on the Hub: the steps appear as boxes joined by arrows on a drawing area (the canvas). See Edit a workflow.
- The classic Workflows page (
/workflows), for the three things the Hub does not have yet: the full history of each run, Follow-ups and the Every task in a workflow setting.
See your workflows on the Hub
- Browser: open the dashboard. The Hub is the first page you see.
- Select Workflows in the nav on the left, under Automation. The number next to it is how many workflows this machine has. On a phone, select More in the bottom bar, then Workflows. The page's address is
/hub#page=workflows. - Each workflow is one row. It shows:
- its name, and its state: Running, Last run failed, Done, Waiting (a step waits for someone), Never run, Off, or Held (it would clash with another way the same events are handled, so it takes no runs until that is fixed);
- what starts it, in words, such as Started by hand, Fridays at 16:00 or When a message arrives by email;
- its agents and its project;
- its last runs as small squares, oldest on the left: green finished, red failed, blue running, amber waiting, grey stopped;
- on the right, a switch that reads On or Off.
- A run that failed adds a red line under the row: when it stopped, and at which step.
- Workflows that need a look come first: a failed last run, then running ones, then the rest by name. Off ones come last.

Demo data; your workflows will differ.
The line under the tabs counts your workflows, how many are on, and the runs of the last seven days. The page refreshes with the rest of the Hub, every minute, and when you select Refresh.
The page shows the newest 100 runs first. Older runs, up to 500, fill in a moment later. Until they are in, a workflow with no run on screen shows no looks stale hint yet.
Find one workflow
- Select a tab: All, Running, Failed or Off. The number on Running and Failed is how many workflows are in it.
- Type part of a name, a project or an agent in Filter workflows.
- Pick a project in All projects. No project lists the workflows that have none.
- The address keeps what you picked, so you can save or share it as a link.
Spot a workflow nobody uses
A workflow that is off and has not run for 30 days shows looks stale in amber, with how long it has been quiet (no run for 41 days, or never run). It is a hint to delete it or turn it back on in the editor. Jobs does the same for schedules.
See the last run step by step
- Select a workflow's name. Its last run opens under the row.
- The first line says when the run started, how it ended, how long it took and what started it.
- Under it, one line per step: a green tick for a step that finished, a red mark for the step where it stopped, with the reason, and a grey circle for steps it did not reach. Each step names the agent that did it and how long it took.
- Under the steps:
- Run again starts it once more with the same input as that run.
- Open in the editor opens the workflow on the canvas, in the same tab. See Edit a workflow.
- All runs opens the classic page, where every run is listed.
- Select the name again to close it.
Start a run
- On the Hub's Workflows page, select Run… under a workflow that is on.
- A box opens. Fill in the inputs the workflow asks for. A field marked * is needed.
- To send the input as text in JSON format instead, open Inputs as JSON.
- Read the line above the buttons: it says who does the steps, and, for a workflow that something else normally starts (a message or a time of day), that this run stands in for that.
- Select Start the run. The box closes and the line at the top of the page says Started. The workflow opens on its new run.
To close the box without starting anything, select Back or press Escape.

Turn a workflow on or off
- On the Hub's Workflows page, select the switch on the workflow's row.
- The line at the top of the page says what changed. When it is Off, nothing starts it any more; runs already under way go on. When it is On, what starts it starts a run again.
This saves the workflow the same way the editor does. A workflow marked Held has no switch: fix the clash it names, then turn it on in the editor.
On a phone
On a phone, the page lists the same workflows and tabs, and opens a workflow the same way. It has no switches and no Run… buttons: starting a workflow, and turning one on or off, are done on a computer. The editor opens on a phone too; see The editor on a phone.

See what is being followed
Workflows that agents started for your requests are listed under Follow-ups, at the top of the left column of the classic page, one group per tag (such as client:example-co). On the Hub's Workflows page, the Follow-ups box on the right counts them; select Show them to open the classic page.
- Browser: on the classic page (
/workflows), look at Follow-ups. Groups with a blocked run are open. - Browser: click a group's name to open it. Each run shows the step it is on, what it waits on and since when.
- Browser: click a run to open its steps.
See Let a workflow follow a request.
Run every task through a workflow
Below Follow-ups, on the classic page, the card Every task in a workflow turns on the setting that runs each task an agent gets inside a workflow run, for every agent or one at a time.
- Browser: click Every task in a workflow to open the card.
- Browser: tick Run every task through a workflow, or open Per agent and choose on or off next to an agent.
See Run every task through a workflow.
Edit a workflow
The editor is a page of the Hub. It has two columns: a side menu on the left and the canvas on the right. The Hub's nav shrinks to its icons, so the canvas gets the room.

Demo data; your workflows will differ.
Open the editor
- Browser: on the Hub, select Workflows in the nav.
- To change a workflow, select its name, then Open in the editor. To start a new one, select New workflow next to the page's title.
- The editor opens in the same tab. Its address is
/hub#page=editor&e-wf=followed by the workflow's ID (its short name), so you can save it as a bookmark. The old address,/workflows/editor?id=…, opens the same page.
A workflow that has never been laid out (for example one written as a file) is arranged for you when it opens.
Read the canvas
- Each step is a box. The small line above its name says what it does, such as Ask an agent or Send a message.
- Arrows run from left to right in the order the steps run.
- A step that can go more than one way has one dot per way on its right edge, each with its name. A choice ("If this, then that") has one dot per case, such as status, new and other. Ask the owner has yes, no and expired.
- A dashed arrow that goes back under the boxes is a loop: the run goes back to an earlier step, for example to try again.

Change a step
- Select a box on the canvas. The side menu shows This step with its settings.
- Change what you need. The status next to the title turns to unsaved.
- Select Save, or press ⌘S (Ctrl+S on Windows and Linux). The status turns to saved.
Save writes only what you changed. The rest of the workflow file stays as it was, including settings the editor does not show (such as its tags or the agent that owns it) and the date it was created. Where the steps sit on the canvas is kept in a separate layout file, so moving or arranging steps does not change the workflow file at all.

To see the whole workflow's settings again, select an empty spot on the canvas. The tab then reads Workflow.
Add and connect steps
- In the side menu, select Add a step.
- Select a step in the list. It lands in the middle of the canvas, ready to set up. You can also drag it onto the canvas, to a place you choose.
- To connect two steps, press on a dot on the right edge of the first box and drag to the second box. Let go when the box is outlined.
- To remove a step or an arrow, select it and press Delete.
Make room on the canvas
- Fold the side menu: select the panel button at the far left of the toolbar, the × in the menu, or press
[. The canvas grows into the space. Select the button again to bring the menu back. The editor remembers your choice. - Arrange: select Arrange in the toolbar, or press
L. The steps are laid out from left to right, with no box on top of another, a choice's cases in their order from top to bottom, and loops drawn underneath. Arrange is one step you can undo. - Fit: select the fit button in the toolbar or at the bottom left, or press
F, to see the whole workflow. Use + and −, or Ctrl and the mouse wheel, to zoom. Drag an empty spot to move around.

Keyboard
| Key | What it does |
|---|---|
| ⌘S / Ctrl+S | Save |
| ⌘Z / Ctrl+Z, ⌘⇧Z / Ctrl+Y | Undo, redo |
| Tab, then Enter | Move between steps, select one |
| Arrow keys (Shift for bigger moves) | Move the selected step |
| Delete | Remove the selected step or arrow |
| ⌘D / Ctrl+D | Copy the selected step |
L | Arrange |
F | Fit the workflow in view |
[ | Fold or unfold the side menu |
/ | Find a step to add |
| ⌘Enter / Ctrl+Enter | Preview |
? | Show these keys |
Describe it instead
To describe the automation in plain English, select Ask AI to build… at the bottom right. See Describe what you want. Read a proposed workflow before you select Apply to canvas: it replaces everything on the canvas. Save only when the steps and destinations match what you intend.
Preview walks through the steps on screen; it does not run them. To run a workflow for real, use Run… on the Workflows page.
Leave the editor
Select Workflows at the left of the toolbar, or any page in the nav. If there are changes you have not saved, the editor asks first. Select Cancel to stay.
The editor on a phone
On a phone, the canvas takes the whole screen above the bottom bar. The side menu starts folded: select the panel button at the top left to open it over the canvas, and × to close it. Drag with one finger to move around.

Who can change a workflow
Only the owner saves, deletes or lays out a workflow, and only the owner can use Ask AI to build…. The owner is whoever opens the Hub on the machine itself, or signs in with the dashboard token. Anyone else can open the editor to look: there is no Save and no Add a step, and the side menu says so. The dashboard refuses their changes even if they are sent another way.
Check it worked
- Browser: after Save, the editor shows saved. Select Workflows at the left of the toolbar: the workflow is listed, and for a new one the number next to Workflows in the nav went up by one.
- Open the workflow in the editor again and select Arrange: every step is visible, none on top of another, and the arrows run from left to right.
- On the Hub, select Run… on a workflow you start by hand, then Start the run. The line at the top says Started, and a blue square appears at the right of the row's squares. After Refresh, once it finishes, the square turns green and the opened run lists each step with a tick.
- Select the switch on a test workflow. It reads Off, and the workflow is under the Off tab. Select it again to turn it back on.
- Follow Check that it worked to confirm the result reached its destination.
If something is wrong
- The Hub says "Could not read the workflows": the dashboard could not ask the machine. The rest of the Hub still works. Select Try again; if it persists, check the machine with
agentx daemon status. - The Hub says "Only the owner can start, turn on or turn off a workflow": the dashboard did not accept your key. Open the Hub on the machine itself, or sign in with the dashboard token, then try again.
- "Could not start …: workflow … is disabled": the workflow is off. Turn it on with its switch first.
- No switch and no Run… on a row: you are on a phone (use a computer), or the workflow is Held (fix the clash in the editor).
- Save fails with a message: the workflow has a mistake, such as a step with no agent. Fix the step the message names and save again.
- "Saved, but the step positions were not": the workflow was saved, but the machine refused the layout. Select Arrange or move a step, then save again.
- "Not saved: …" with a network error: the machine did not answer. Nothing was written. Check it with
agentx daemon status(in a Terminal on that machine), then save again. - There is no Save button, and the side menu says only the owner can change the workflow: you opened the Hub from another computer without signing in. Sign in with the dashboard token, or open the Hub on the machine itself.
- The editor says "The editor could not be loaded": the page could not fetch the editor. Refresh the page. If it keeps happening after an update, run
pnpm build(from a source checkout) and restart the daemon. - The canvas looks empty: the steps are outside the view. Press
For select the fit button. - An arrow leaves from a dot named after a case that no longer exists: the choice's cases changed and the arrow kept its old name. Select the arrow and delete it, then connect the right dot again.
- A workflow that normally starts on an event will not start by hand: Run… on the Hub starts it anyway; the line above the buttons says this run stands in for that start. If it still does not start, the workflow is off or Held.
- Ask AI to build… answers with an error: the assistant needs an agent with a working model. See Describe what you want.
- A run stops at a step: on the Hub's Workflows page, select the workflow's name and read the reason on the step marked red. See Check that it worked.
