Work with your agents, not just through them

Look up the YAML fields, CLI commands, execution rules, and retained results for hob automations.

Use this reference for the detailed automation contract and examples. Start with Automations to build and run the guestbook check-and-review workflow. Continue with Building automations to add inputs, validated agent results, and deliberate failure behavior. Use Secrets, schedules, and trust to prepare unattended work.

Definition and bundle

Where automations live

Scope	Location	Shared with team?
Shared	`.hob/automations/<uuid>/` in the project's canonical checkout	Yes
Private	`{configDir}/automations/{projectID}/<uuid>/`	No
Global	`{configDir}/automations/global/<uuid>/`	No

Field or rule	Contract
`version`, `id`, `name`	Version `1`, UUID identity, required display name. Installed directory UUID matches `id`; `init` generates it
`description`, `category`	Optional description and grouping label
Action	Exactly one of `command` or `steps`
`command`	Shell source normalized to a foreground `run` step with `id: main`; source YAML remains unchanged
`shell`, `surface`, `pty`	Top-level forms only with `command`; explicit plans put them on the owning step
Assets	Keep scripts, templates, styles, and schemas inside the bundle; `scripts/`, `assets/`, and `schemas/` are useful conventions
Validation	Rejects unknown fields, extra YAML documents, symlinks, invalid identity, and oversized bundles
Bundle limits	At most 256 supporting files and 16 MiB of supporting content
Staging	Ordinary staging-directory names are accepted; installed bundles use UUID directories
Draft	Inactive until applied; retained for editing, absent from the runnable registry
Run snapshot	Captures the complete hash-checked bundle and static nested bundles; live edits do not change an admitted run

These definitions have the same execution plan:

Command shorthand

version: 1
id: 5af1c74e-f97a-4db8-9eca-e76b9ed5afe3
name: Guestbook check
shell: sh
command: node --check app.js

Explicit step

version: 1
id: 5af1c74e-f97a-4db8-9eca-e76b9ed5afe3
name: Guestbook check
steps:
  - id: main
    name: Guestbook check
    shell: sh
    run: node --check app.js

CLI

Both people and agents use the same managed registry. Commands below begin with hob automation, except the final view command. Use --help for command flags.

Command	Result
`list [--scope shared\|private\|global]`	Registry entries, including invalid definitions and diagnostics
`init <name> [--scope …]`	Create a scaffold; default scope is shared
`init --stdin [--scope …]`	Create from a complete ID-free definition; invalid input writes nothing
`init --bundle <dir> [--scope …]`	Create from an ID-free manifest plus all supporting assets, atomically
`show <id-or-name>`	Definition details and exact managed paths
`apply <id-or-name> --stdin`	Validate and replace the complete definition; preserve identity
`apply <id-or-name> --bundle <dir>`	Replace manifest and all assets together; include everything to retain
`validate <bundle-or-automation.yaml>` or `validate --stdin`	Anchored diagnostics without saving or running
`inspect <id-or-name> --step <id> --data-file <json>`	HTML template injection and inline JavaScript preflight; no run or durable artifact
`run <id-or-name> [--input key=value …]`	Start with repeatable structured input values
`run <id-or-name> --inputs-json <json-or->`	Supply a string-valued JSON object; `-` reads stdin
`run <id-or-name> --wait [--timeout <seconds>]`	Wait for completion; default wait limit 300 seconds, exit 0 only on success
`runs [<id-or-name>]`	Recent run states and results
`logs <run-id>`	Captured output
`delete <id-or-name>` / `restore <id-or-name>`	Move the complete automation to Trash / restore it
`delete <id-or-name> --permanent`	Delete an already trashed automation, including its history and stored assets
`hob open view automations`	Open the full Automations view

Authoring context	Rule
Linked builder agent	May omit the automation ID for `show`, `apply`, and `inspect`; the pane identifies its automation
New inactive draft	Author inside its provided bundle, then promote with `apply --bundle "$HOB_AUTOMATION_DIR"`
Saved automation	Stage a complete asset replacement before `apply --bundle`; use `apply --stdin` for a definition-only change
Invalid apply	Returns diagnostics, exits 1, and leaves the working copy unchanged
Shared run	May pause for human trust approval; the CLI cannot approve it
Nested execution	Automation shell steps use an `automation:` step, not recursive `hob automation run`

Run directories and outputs

Name	Meaning
`HOB_AUTOMATION_DIR` / `${{ automation.dir }}`	Captured authored bundle during execution; read scripts, templates, and schemas here
`HOB_RUN_DIR` / `${{ run.dir }}`	Writable run output directory; write generated files here
`HOB_OUTPUT`	Private output-record file for the current process step; watched while it runs
Single-line record	Append `NAME=value` followed by a newline
Multiline record	Append `NAME<<END`, newline, value lines, then a line containing only `END`; choose a delimiter absent from the value
Output limits	Up to 128 named values, each bounded to 256 KiB
Published value	Later steps read `${{ steps.<id>.outputs.NAME }}`; stdout is not a control channel
Cleanup	Captured artifacts remain in history after temporary run output is removed

Steps

YAML examples below are fragments unless they include version. Add them to a complete definition; provide any referenced scripts, schema files, and child automations.

Common field	Contract
`id`, `name`	Required; IDs are unique across steps and finally, matching `[A-Za-z_][A-Za-z0-9_-]*`
`description`	Optional step description
Action	Exactly one: `run`, `exec`, `agent`, `present`, `automation`, `web`, or `refresh`
`if`	One condition expression; false records a skipped step
`os`	`windows`, `macos`, or `linux`, or a list of them; on another system the step is skipped
`on-error`, `retry`, `timeout`	See Control flow and results
`parallel`	Consecutive new-agent cohort name; see parallel constraints
`env`, `cwd`	Process steps only (`run` or `exec`); top-level forms supply automation context
Environment names	`[A-Za-z_][A-Za-z0-9_]`; `HOB_`, `FORCE_COLOR`, and `CLICOLOR_FORCE` are reserved
`artifacts`	Explicit files to capture at the step; forbidden within parallel cohorts

Process steps

Field	Contract
`run`	Static shell source; use for pipes, redirects, or chaining
`shell`	Optional platform default, or `sh`, `bash`, `zsh`, `fish`, `pwsh`, `powershell`, `cmd`; valid only with `run`
`exec`, `args`	Static executable plus argument list; arguments support interpolation without shell expansion
`detach: true`	Valid on `run` and `exec`; launches in the background and moves on, so later completion is not the step's result
Detached constraints	No `timeout`, `surface`, or `pty`; captured bundle/run paths stay available until process exit
`surface`, `pty`	Foreground process status; see Surfaces and retained results
Supporting helper	Prefer authored Bash under `scripts/`, explicitly invoked with `exec: bash`; use the actual executable when wrapping existing project tooling

Agent steps

Field or result	Contract
`prompt`	Required, interpolated, never secret-bearing
`permission-mode`	Required for a new pane: `ask`, `approve_all`, `deny_all`, `plan`, or `plan_approve_all`
`backend`, `model`, `effort`	Optional static picker values; omitted values use normal pane defaults
`account`	Backend account; an explicit empty string selects its default account
`pane`	Reuse an existing conversation, usually `${{ steps.review.pane-id }}`; backend/model/effort/permission-mode overrides are invalid
Reused context	Conversation stays intact; each step has its own prompt marker, transcript slice, status, and result
`result.format`	`json`
`result.schema`	Static self-contained schema under `${{ automation.dir }}/…`; validates this step's immediate response
Accepted JSON	Bare JSON or one JSON Markdown fence; only validated canonical JSON becomes the result
Contract scope	Constrains result shape, not the correctness of the agent's work
Result access	`steps.<id>.result`; compatibility spelling `steps.<id>.outputs.output`

Structured agent result

- id: review
  name: Review the guestbook
  agent:
    prompt: Review app.js without editing it and return your verdict as JSON.
    permission-mode: ask
    result:
      format: json
      schema: ${{ automation.dir }}/schemas/review.schema.json
  on-error: retry
  retry:
    max-attempts: 3

The complete Building example includes the schema. hob supplies its contents to the agent; the prompt need not repeat them.

Presentations

Field	Contract
Source	Exactly one of `file`, `content`, or `template`; captured when execution reaches the step
`file`	Existing regular file; `as` may be `auto` (default), `source`, or `web`
File inference	Extension selects Markdown, HTML, image, video, audio, PDF, or source rendering
`content`	Inline text; explicitly set `as: markdown`, `source`, or `web`
`template`	Authored HTML; always web, with exactly one `__HOB_DATA__` marker in JavaScript value position
`data`	Template-only mapping; valid JSON values become native JSON types, other values stay strings
Capture	Safely serialized data and an immutable run asset; HTML uses a sandboxed web view
Paths	Run directory is the generated-file convention; an explicitly managed accessible regular file elsewhere can also be captured

assets/report.html

<script>
  const report = __HOB_DATA__;
</script>

Template presentation

- id: show-report
  name: Show report
  present:
    template: ${{ automation.dir }}/assets/report.html
    data:
      review: ${{ steps.review.result }}

Use hob automation inspect with concrete JSON before handing over a template automation.

Nested automations

Field or rule	Contract
`automation`	Static `shared:<uuid>`, `private:<uuid>`, or `global:<uuid>`; names and paths are invalid
`inputs`	Child input names mapped to interpolated parent values; no secrets or secret-marked inputs
`secrets`	Child secret name → parent secret name; both definitions must declare their respective names
`timeout`	Optional positive duration; cancellation stops the child
Outputs	Child's top-level outputs become `steps.<nested-id>.outputs.<name>`

Nested step

- id: child-review
  name: Run the shared review
  automation: shared:44444444-4444-4444-8444-444444444444
  inputs:
    scope: ${{ inputs.scope }}
  secrets:
    SERVICE_TOKEN: REVIEW_TOKEN
  timeout: 10m

Replace the illustrative UUID with the child's installed ID.

Web steps

A web step runs one flow in a web pane: the same flows and the same Host engine as hob web flow run (see hob web --help for the step grammar). Web panes render only in the hob desktop app. A web step therefore runs only while a hob desktop app is attached to the Host, on the same machine or from another one; with none attached, or with only the browser IDE or hob mobile, it fails at once with pane_unavailable (no desktop). A desktop app that disconnects during the step fails it the same way.

Field	Contract
`file`	A flow file. Same path rules as `present` `file`: interpolated, relative to the automation's working directory; use `${{ automation.dir }}/flows/…` for a file in the bundle (covered by the bundle's trust hash)
`steps`	Inline flow steps instead of `file`; exactly one of the two
`url`	Where the flow starts; replaces the flow's own `url:`. Interpolated. A flow file's `url:` can also use `${{ vars.x }}`, for example a base URL from this step's `vars`
`pane`	Run in an existing web pane, for example `${{ steps.sign-in.pane-id }}`; without it, the flow opens a new pane
`show`	`on-failure` (default): a new pane that no window shows; a failed flow keeps it and shows it in the run's window, or records an Open pane link when the run has no window. `never`: a failure stays hidden with its link. `always`: the pane opens in the run's window; a run without a window runs the step hidden and says so in its output
`keep`	`true` keeps a passing new pane for a later step until the run ends
`vars`	Flow variable → interpolated value; fills `${{ vars.x }}` in the flow
`secrets`	Flow secret → declared automation secret; fills `${{ secrets.x }}` in the flow. Secret values never reach outputs or output text
`pace`	`fast`, `human`, `demo`, or milliseconds
`timeout`	The lower of the step's timeout and the flow's own timeout (at most 300 s) is the flow's budget

Inside a flow, ${{ vars.x }} and ${{ secrets.x }} are flow variables, set by the step's vars and secrets; automation expressions apply only to the step's file, url, pane, and vars values.

Reference	Value
`steps.<id>.status`	`success` when the flow passed; `failure` when a step failed or the flow could not run
`steps.<id>.pane-id`	The kept pane, for a later `web` step's `pane`
`steps.<id>.outputs.passed`	`true` or `false`
`steps.<id>.outputs.failed-step`	The first failed step, for example `step 2 expect text=Paid: timeout`
`steps.<id>.outputs.artifacts-dir`	`${{ run.dir }}/web-flows/<id>`: steps log, result, final snapshot, and failure screenshot
`steps.<id>.outputs.open-pane`	The Open pane link of a kept hidden pane
`steps.<id>.outputs.<name>`	Each `read … as: <name>` value in the flow

The run keeps the steps log and the failure screenshot as step artifacts and shows the screenshot and an Open pane button in the run log. A pane kept with keep: true closes when the run ends, unless a later failure keeps it; a scheduled run leaves no hidden panes behind. hob automation validate parses each flow and notes that web steps need an attached desktop app.

flows/sign-in.yaml

name: Sign in
url: ${{ vars.base }}/login
steps:
  - fill: label=Email
    value: ${{ vars.email }}
  - fill: label=Password
    value: ${{ secrets.password }}
  - click: role=button[name="Sign in"]
  - expect: role=heading[name="Account"]

Web steps

version: 1
id: 3b1f7c2e-8d4a-4c6b-9e2f-5a7d1c0b4e93
name: Checkout smoke test
inputs:
  base-url:
    default: http://127.0.0.1:4870
secrets: [SHOP_PASSWORD]
steps:
  - id: sign-in
    name: Sign in
    web:
      file: ${{ automation.dir }}/flows/sign-in.yaml
      keep: true
      vars:
        base: ${{ inputs.base-url }}
        email: [email protected]
      secrets:
        password: SHOP_PASSWORD
  - id: checkout
    name: Check out one item
    if: ${{ steps.sign-in.status == 'success' }}
    timeout: 3m
    web:
      pane: ${{ steps.sign-in.pane-id }}
      steps:
        - click: role=button[name="Add to cart"]
        - click: role=link[name="Checkout"]
        - read: role=status
          as: order
        - expect: {text: role=status, contains: "Order placed"}
  - id: report
    name: Report the order
    exec: echo
    args:
      - "Order ${{ steps.checkout.outputs.order }}; artifacts in ${{ steps.checkout.outputs.artifacts-dir }}"

Refresh

refresh: on-reconnect arms connected browser clients to reload once a replacement backend is serving. Use it for a rebuild-and-relaunch workflow, not to refresh a report.

Control flow and results

Step failures, retries, and timeouts

Field or outcome	Rule
`on-error: fail`	Default; failure stops the plan
`on-error: continue`	Records failure and lets later steps run
`on-error: retry`	Requires `retry.max-attempts`, 2–20 total attempts
`retry.delay`	Optional positive duration; `retry` is invalid with other error policies
`timeout`	Positive duration on foreground `run`, `exec`, `agent`, nested, or `web` steps; timeout records `timed-out`
Ordinary failure	Retry starts the step again
Invalid agent JSON	Retry supplies validation feedback in the same conversation
Invalid schema file	Setup failure, not retried
`steps.<id>.status`	`success`, `failure`, `canceled`, `timed-out`, `interrupted`, or `skipped`
Skipped condition	Empty exit code, not `0`; cannot satisfy a success-by-exit-code check
Not run	Remaining planned steps retain a Not run outcome after failure or cancellation

Gating a step on an earlier one

Continue after a failed check

- id: check
  name: Check syntax
  exec: node
  args: [--check, app.js]
  on-error: continue
- id: report
  name: Report a failed check
  if: ${{ steps.check.status != 'success' }}
  run: echo 'The syntax check needs attention'

Steps for one operating system

A step with os runs only on the systems it names and is recorded as skipped on the others. Use it for commands that differ between systems:

Open the report on each system

- id: open-mac
  name: Open on macOS
  os: macos
  exec: open
  args: [report.html]
- id: open-other
  name: Open on Linux or Windows
  os: [linux, windows]
  run: xdg-open report.html || start report.html

Skills run no commands on this computer. When work needs commands that run here, or different commands per system, put it in an automation.

Run agent analysis in parallel

Constraint	Rule
Membership	Up to 8 consecutive new-pane agent steps with the same `parallel` identifier
Ordering	Cohort name is contiguous and single-use; next step waits for every member
References	Earlier steps allowed; sibling references forbidden
Exclusions	No pane reuse, retry, artifacts, process/nested/present/refresh actions, surfaces, PTYs, or detach
Failure	Wait for all members; required failure fails the run, while `on-error: continue` permits downstream synthesis
Stop or timeout	Cancels live members, waits for settlement, then bounded finally cleanup
Automatic execution	Every member needs a finite timeout and `approve_all` or `deny_all`; also applies through a scheduled parent into nested work
Interaction	Manual cohorts may ask questions; automatic cohorts reject ask-user and plan-exit prompts
Shared files	Distinct pane/run directories do not isolate repository edits

Cleanup with finally

Rule	Contract
Start boundary	Runs after execution environment preparation, including runtime failure or user Stop
Earlier failure	Queued cancellation, input failure, or environment-resolution failure does not run cleanup in an unrelated checkout
Actions	Only `run` or `exec`, each with a required timeout
Exclusions	No detach, surface, or PTY
Identity	IDs share the main steps' namespace
Failure	Failing cleanup makes an otherwise successful run fail

Expressions

Form	Contract
Interpolation	`${{ reference }}` substitutes a string; each token contains one bare reference
Locations	Env, arguments, step cwd, prompts/pane targets, presentations, surfaces, artifacts, nested inputs, outputs; secret restrictions still apply
Condition	Entire `if` value is one `${{ … }}` expression
Operators	`==`, `!=`, `!`, `&&`, `\|\|`, parentheses; precedence: `!`, then equality, `&&`, `\|\|`
Literals	Single-quoted strings with next-character escapes, double-quoted Go-style strings, `true`/`false`, unsigned decimal text
Equality	Exact string equality, including numeric literals
Truthiness	After trimming whitespace, non-empty and neither `0` nor `false`

Reference	Value
`inputs.<name>`	Declared input value
`secrets.<NAME>`	Declared secret in permitted locations
`steps.<id>.exit-code`	Earlier step's exit code; empty for skipped
`steps.<id>.status`	Earlier step's conclusion
`steps.<id>.pane-id`	Earlier agent step's pane
`steps.<id>.prompt`	Fully expanded agent prompt
`steps.<id>.result`	Agent's final answer, canonical JSON when a result contract applies
`steps.<id>.outputs.<name>`	Published process or child-run output
`hob.web-ide`	`true` when the browser IDE is served, otherwise `false`
`automation.dir`, `run.dir`	Captured bundle and writable run directories
`run.id`	Available for execution-environment branch/start-point expressions

What expressions deliberately leave out

Unsupported	Use instead
Functions, arithmetic, JSON property traversal	Process the value as data in a shell/executable step
Operators in interpolation tokens	Conditions in `if`; plain references elsewhere
Dynamic `run`, executable path, health probe, child reference, backend/model/effort	Static program selection; pass data through env or args
Arbitrary top-level cwd interpolation	Only `${{ automation.dir }}` or `${{ run.dir }}` roots there; use step cwd for dynamic process paths

Inputs and outputs

Inputs

Types: text (default), textarea, choice, bool, number, integer, date, time, datetime, file, directory. Names match [A-Za-z_][A-Za-z0-9_-]*.

Field	Valid for	Meaning
`description`	all	Label shown in the run form
`default`	all	Prefilled value; must itself pass the input's validation
`placeholder`	text, textarea, number, integer, date, time, datetime	Hint text shown while empty
`options`	choice	The selectable values — at least one, non-empty, unique
`multiple`	choice, file, directory	Allow several selections; the value becomes a YAML list
`min` / `max`	number, integer, date, time, datetime	Inclusive bounds; `min` must be ≤ `max`
`step`	number, integer, time, datetime	Increment from `min` (or 0 / midnight); seconds for temporal types
`rows`	textarea	Editor height in rows
`accept`	file	File-type filter for the picker
`appearance`	choice	`auto`, `select`, `radio`, `segmented`, `checkboxes`, or `chips`
`secret`	text, textarea, number, integer, date, time, datetime	Password-style field, scrubbed from logs and history, barred from the same display sinks as declared secrets
`group` / `group-title` / `group-description`	all	Group related inputs in the run form
`show-when`	all	Show the input only when other inputs have expected values

Conditional input

inputs:
  scope:
    type: choice
    options: [app, styles, all]
  review_note:
    type: textarea
    required: false
    show-when:
      scope: [styles, all]

Input rule	Contract
Required	Defaults to true; `required: false` permits empty
`show-when`	All mapped conditions must match; a scalar is equality, a list is any-of
Hidden value	Must remain empty; supplying one fails the run
Dependencies	Self-reference and cycles rejected
Automatic triggers	Structured inputs prohibited even with defaults; no interactive PTY input

Automation outputs

Top-level outputs: { verdict: "${{ steps.review.result }}" } publishes named values to a parent via its nested step's outputs. Values cannot contain secrets.

Execution environments

Definition sourcing and execution targeting are separate. Shared bundles come from the canonical checkout; choosing a worktree to execute in does not select its copy of the definition.

Field	Contract
Omitted	Manual/nested runs inherit the admitted environment; scheduled/restart runs use the project default
`environment: default`	Pin the project checkout
`environment: floating`	Use the project checkout while permitting branch changes; later steps see its current files
`environment.branch`	Local target branch; global automations cannot target a branch
`environment.if-missing`	`fail` (default), or `create`
`environment.start-point`	Explicit committed ref required for creating a missing branch
Branch expressions	Only non-secret `inputs.*` and `run.id` in branch/start-point fields
Manual override	`run --environment <id>` or `--branch <name> [--if-missing create --start-point <ref>]`; literal values, no expressions

Execution rule	Contract
Worktree	Reuse a matching hob environment or create a managed worktree for an unoccupied branch; reject unattached external worktrees
Creation	No dirty-file copy, visible workspace, or switching of another checkout
Cwd	Within resolved environment, captured bundle, or run directory; arbitrary outside working directories invalid
Pinned identity	Commits allowed on the pinned branch; changing that branch or pinned detached commit fails the run
Floating identity	Initial branch/HEAD retained as provenance; branch changes permitted
Detached lifetime	Bundle/run paths retained until exit; if the Host exits first, it leaves them available
History	Records definition source/hash, execution branch/initial HEAD, creation and override markers; Open in workspace reveals the target
Branch lifecycle	No automatic cleanup, deletion, merge, rebase, push, commit, or checkout

Secrets

For setup and a worked example, see Secrets, schedules, and trust.

Field or boundary	Rule
Declaration	Top-level `secrets: [NAME]` lists every required secret
Resolution	Host environment variable → project store → global store; missing required values fail setup
Stored project/global values	Encrypted at rest; replacement UI does not reveal the saved value
Automation-level value	An `env:` entry in the definition, not encrypted secret storage
Allowed secret expressions	Automation/step `env`, `exec` arguments, step `cwd`, and `if` conditions; prefer step-level environment variables
Rejected secret expressions	Agent prompts/panes/result schemas, presentations, surfaces, artifact paths, outputs, and nested inputs
Secret inputs	Inputs marked `secret: true` are barred from the same display sinks
Nested delivery	Explicit child-name → parent-name `secrets` mapping; both definitions declare their names
Scrubbing	Known values are scrubbed from automation output and history; arbitrary files and transformed values are outside that guarantee

Triggers

Scheduling

For the worked setup, see Run a check each night.

Field	Contract
`on.user-trigger`	Default true; false removes manual Run for people, agents, and CLI
`on.schedule`	At most 64 entries; same cadence with conflicting policies rejected
`every` elapsed	Nominal start-to-start spacing, 1s–2880h; examples `30m`, `1h30m`, `24h`
`every` calendar	Integer `d`, `w`, `mo`, count 1–120; `m` means minutes
`at`	Required `HH:MM` for calendar schedules
`weekday`	Required for weeks; `sun` through `sat`, rejected for other intervals
`day`	Required for months; 1–31 or `last`; missing numbered dates skipped
`timezone`	Default Host `local`; pin an IANA zone for consistent shared wall-clock time
`dst`	`compatible` (default), `earlier`, `later`, `skip`; invalid with a fixed-offset zone
`missed-run`	`skip` (default) or at most one catch-up with `run-once`; elapsed schedules skip missed ticks
`overlap`	Derived from `concurrency`; explicit value must match it
`concurrency`	`allow`, `forbid` (default), `queue`, `replace`; queue coalesces scheduled ticks into at most one pending run

Scheduling rule	Contract
Availability	Running Host with project open, including headless; another window does not duplicate scheduling
Interaction	No structured inputs, even defaulted, or interactive PTY; automatic agent cohorts have additional constraints
Calendar phase	First matching selector anchors the recurrence; cadence persists across project close
Compatible DST	Spring gap moves forward; fall repeat runs once at the earlier occurrence
Skip DST	Drops both nonexistent and ambiguous local times
Shared trust	Human trust and automatic-run permission required before scheduled execution

Elapsed and calendar schedules

on:
  schedule:
    - every: 30m
    - every: 1d
      at: "09:00"
      timezone: America/Chicago
    - every: 2w
      weekday: tue
      at: "09:00"
    - every: 1mo
      day: last
      at: "09:00"
      missed-run: run-once

Start an automation with the project

See the service recipe for setup and the schedule/restart comparison.

Field or action	Rule
`restart`	`no` (default) or `unless-stopped`
Eligible plan	Exactly one foreground shell `run` step, including `command` shorthand
Concurrency	Must be `forbid` (default)
Interaction	No structured inputs or `pty: { input: true }`
Activation	Declaring the policy makes it eligible; a manual Run activates it
Running service	An existing manual run can be adopted without starting a second copy
Stop	Deactivates lifecycle restart until another manual Run
Project load	An active policy starts a fresh process through a staggered queue
Exit blocking	Restart-managed services do not block project/window close by default; `block-on-exit: true` opts in

Health checks

Only valid with restart: unless-stopped. See Check that the service is responding.

Field	Rule
Probe	Exactly one of `http` (absolute HTTP(S) URL), `tcp` (`host:port`), or `run` (shell command)
`shell`	Optional shell for a `run` probe
Probe target	Static; no expressions. Pass values through automation `env`
`interval`	Elapsed duration, minimum `2s`, default `30s`
`timeout`	Positive, no greater than interval, default `3s`
`start-period`	Startup grace before first probe; none by default
`failures`	Consecutive failures before unhealthy, 1–100, default 3
`successes`	Consecutive successes before healthy, 1–100, default 1
`on-unhealthy`	`report` (default) surfaces state; `restart` also restarts the process

Trust

Trusting shared automations

See Review shared work before it runs for the approval step.

Decision	Rule
Initial trust	Human confirmation before the first shared run, including agent, CLI, and nested requests
Recorded identity	Local hash of the canonical execution definition; an equivalent command-to-step rewrite preserves it
Automatic runs	Require trust plus recorded automatic-run permission; the trust box grants both when the definition declares a schedule or restart policy
Editor save	Can carry an existing trust record and automatic-run choice to the saved version
External change	A repository update or external edit that changes the trusted execution definition requires renewed review
Approval owner	The person using hob; an agent cannot approve it

Surfaces and retained results

Surface a live value or link

Field or form	Contract
`surface: url`	First matching HTTP(S) URL from output, opened in a hob web pane
`regex`, `group`	Extract a match; default group is first capture, or whole match without captures
`label`	Optional display label
`value`	Interpolated named output, such as `${{ outputs.progress }}`
`search-timeout`	First-match search window; default 5 minutes
`update`	`once` (default) or `latest` for changing values
Placement	Top level with `command`, otherwise the owning foreground `run` or `exec` step
Output search	Bounded recent buffer; completed lines only, including carriage-return progress
Updates	Default stops after first match; `latest` continues until process exit, publishing changes only
Named outputs	Event-driven through `HOB_OUTPUT`
`pty: true`	Latest terminal line as read-only status
`pty: { input: true }`	Also accepts keyboard input; not valid for automatic triggers

Live progress

surface:
  regex: '^Progress:\s+(.+)$'
  group: 1
  update: latest

Artifacts

Field or rule	Contract
Declaration	`artifacts: [{ path: "${{ run.dir }}/review.json", name: review }]`
Placement	Top-level or producing step; paths support interpolation, never secrets
Collection	Each path must exist and be a regular file; missing files/directories fail the producing step or run
Snapshot	Exact collected bytes retained after run-local cleanup
Limit	256 artifacts across the automation and all steps

Run history

Record	Contract
Lifecycle	Queued, Waiting, Running, Stopping; separate from final conclusion
Completion	Records success/failure and reasons such as Stopped, Replaced, hob closed, Timed out, Interrupted
Steps	Status, duration, output, transcript slices, and artifacts; Skipped and Not run remain distinguishable
Project History	Runs appear unless muted for that automation
Retention	Completed visible history: 90 days and newest 500 top-level runs per automation; active and explicitly trashed runs excluded from automatic retention

Automation reference

Definition and bundle

Where automations live

CLI

Run directories and outputs

Steps

Process steps

Agent steps

Presentations

Nested automations

Web steps

Refresh

Control flow and results

Step failures, retries, and timeouts

Gating a step on an earlier one

Steps for one operating system

Run agent analysis in parallel

Cleanup with finally

Expressions

What expressions deliberately leave out

Inputs and outputs

Inputs

Automation outputs

Execution environments

Secrets

Triggers

Scheduling

Start an automation with the project

Health checks

Trust

Trusting shared automations

Surfaces and retained results

Surface a live value or link

Artifacts

Run history

On this page