Workflows and schedules

The engine keeps its run history in .hubzoid/dbos.db, or in PostgreSQL when HUBZOID_DBOS_DB or a PostgreSQL DATABASE_URL is set. Workflow state, pauses, personal schedules and the access audit live in the operational database, so every bridge on a shared database sees the same pauses.

Markdown tasks and both kinds share one run history, the same hubzoid schedule pause, resume and cancel commands, and the same hold while hubzoid backup copies the deployment.

• Markdown tasks and scheduled evals start whenever their files exist. HUBZOID_DISABLE_SCHEDULE=1 turns them off.
• Code workflows, reports people run from chat and personal schedules run only where the deployment sets HUBZOID_SCHEDULES=1, or automatically in a deployment that hubzoid run starts from hubzoid.yaml or with several Hubs. A copy of the Hub on a laptop does not fire alongside the server.

One engine owns a Hub at a time, with a file lock on SQLite and an advisory lock on PostgreSQL. A second bridge for the same Hub keeps chat running and takes over when the owner releases the Hub.

Every run first records the account it acts as, in a step named hz_md_identity or hz_run_identity, so a resumed run never switches account midway. A markdown run then has up to four steps: the agent's work (or the run: command), a commit of the paths the task declares under commit:, a push when it sets push: true, and finish. A code workflow's steps are your @step functions and each call to hub.call_llm, hub.call_agent, hub.call_jev, hub.publish_artifact or hub.send_email. Code outside a step runs again when a run resumes, so keep side effects inside steps.

A scheduled run's id is derived from its slot, such as md:monday-brief:20261026T0907@my-hub, so the same slot is never queued twice.

Times use the person's time zone from Settings unless they name one, then the deployment's, then the zone their browser sends, then UTC.

People run, pause, resume, edit and stop their requests under Settings → My schedules. HUBZOID_PROMPT_WORKFLOWS=false turns the feature off for a Hub. On a laptop where schedules are off, the agent says it cannot schedule.

• Inputs. inputs= takes a Pydantic model, read in the run as hub.input. Chat and MCP tools take its schema, Run now in Settings shows a form, and the CLI takes --input key=value. Inputs are stored with the run, so never put a secret in them.
• Run for me. as_tool=True adds a chat and MCP tool that runs the workflow as the person asking, with their grants. schedulable=True lets people save their own schedule of it.
• Access. Each report adds a capability to the agent's Access tab, such as Run Sales report (wf_sales_report). Schedule reports for themselves lets a person save schedules, and Share reports with the company domain lets a run publish a company link. Workflow permissions on the same tab gives finer rights per workflow, such as run, schedule, see runs or pause.
• Personal schedules. "Run the sales report for me every Monday at 9" saves a schedule after a yes. Each run acts as that person, so it stops when their access does. A schedule pauses itself after three failures in a row, or when the person's access or the workflow's inputs change. By default a person may keep 10 schedules per agent, at most hourly.
• Live reports. hub.publish_artifact(..., key=...) adds each publish to a report series with one link that always shows the newest copy. A team run writes the agent's series. Run for me and personal schedules write that person's own series, private to them until they share it.

Administrators see everyone's schedules under Team schedules, with their model cost for the last 30 days, and can pause or stop them. The Hub must be running when a schedule is due.

run_as chooses whose permissions a run uses and grants nothing. It is read only from files and operator configuration, never from an API, a tool or a model. The account must have signed in at least once, not be awaiting approval, blocked or replaced, and hold Use this agent. Otherwise the run fails with an error that names the fix, and Hubzoid never falls back to another account. The account is checked again before every model call, tool call, publish, email and connection.

What the run touches belongs to that account:

Older releases ran a code workflow as the service identity workflow:<name> and a markdown task as workflow:md:<task>. Those grants are kept and labelled Legacy service identity in Settings, but no run uses them. When the account lacks a permission the old identity held, the run log names it. See identity and access.

• Markdown tasks run one at a time per Hub, and scheduled evals share that queue. A due task waits while the Hub is answering chat, then starts on a later tick. A running task continues alongside new chat requests.
• Code workflows run one at a time per workflow by default, and different workflows run side by side. @workflow(concurrency=N) allows more, and concurrency_key keeps runs that share a key, such as one ticket, in order. max_concurrent_workflows: N in workflows/settings.yaml caps the shared queue. There is no cap by default.
• Markdown tasks and code workflows use separate queues, so one of each can run at the same time.

Code workflows run at least once. A completed step is not run again when a run resumes. A step that was running when the process stopped runs again, so its side effects can happen twice. hub.publish_artifact and hub.send_email are recorded steps: a resumed run gets back what it already published and never sends an accepted email again. A hub.call_jev call still in flight when the process stopped is made again, so it can be billed twice. Make every step that changes something outside the Hub safe to repeat:

• Use a key the other system deduplicates on, such as a record id, the run's slot or the webhook event's key.
• Check before you write: does the ticket for this alert already exist?
• Record what you finished as a per-item marker, for example hub.state[f"done:{item_id}"] = True, and skip marked items.

Markdown tasks never repeat their work. If the process stops mid-work, the recovered run fails with an error that starts interrupted by a restart, and the task's state file carries progress to the next run. A run that finished its work but stopped before commit or push resumes from that step.

Retries, timeouts and webhook redelivery are in the workflow API and operating runs.

On a machine where code workflow schedules are off, no catch-up runs and Settings says the schedules are off instead of showing a next run.

Then failed runs, failed scheduled evals, overdue runs, failure streaks and a schedule that stopped firing raise alerts, with a one-hour cooldown. An alert carries the Hub, the kind, the workflow, the run id and a link to Settings, never outputs or exception text. Failed runs always show in Settings → Activity, alerts or not.

A schedule whose scheduled runs fail 20 times in a row pauses itself (pause_after_failures, 0 turns it off). Webhook runs have a 15-minute deadline by default, and scheduled runs have none until you set @workflow(timeout=...) or workflow_timeout. Python code that is already running cannot be stopped at its deadline: an overdue run raises an alert and keeps running until it returns.

Runs belong to the code that started them: a hash of the installed Hubzoid version and every workflows/**/*.py file. Code a workflow imports from outside workflows/ is not part of the hash. When the Hub starts under new code, runs that were queued or interrupted under the old code are cancelled and stay in the list as CANCELLED. A markdown run that was queued but had not started is queued again under the new code.

• The scheduler re-reads schedule/*.md on every tick, so markdown task edits apply without a restart.
• workflows/settings.yaml is read when the bridge starts and at the start of each code workflow run. A mistake in it turns that Hub's workflows off, with the error in workflow health, while chat keeps running.
• Code workflow modules load when the Hub starts. Restart the Hub to pick up a code change, and drain queued runs first as described in operating runs.

The Hub's managers see each run's workflow, status, timing and a failure summary. The result, step outputs and detailed errors are shown only to that account. hubzoid schedule status on the server shows everything.