Step Handler Catalog
Scope: this catalog documents the handler set shipped with the demo/e2e plugin wheels. Handlers are pluggable and installed per instance — your instance lists its live handler set under Settings → Installed Plugins, and the flow editor's step palette shows the same configuration forms rendered from these schemas. In the app, the Help drawer's Installed Handlers topic (on the flow editor) shows the live catalog instead of this pinned one, including each handler's own documentation page when its plugin ships one.
Handlers are grouped into namespaces by their id prefix (for example netcli.* for network-CLI steps). Configuration tables list top-level fields; nested objects are edited structurally in the flow editor.
ansible.playbook
Ansible Playbook · category: Actions · kinds: ACTION, CHECK, EXECUTE
Run an Ansible playbook against the step's target devices, with the inventory and credentials generated from Hegemony's inventory.
| Key | Type | Default | Description |
|---|---|---|---|
timeout_seconds | integer, or empty | null | Timeout (seconds) — Maximum run time of the container, including the image pull. Empty: the step's timeout. A longer time raises the step's timeout to fit. |
memory | string | "" | Memory Limit — Container memory limit, e.g. 512m or 2g. Defaults to 1g. |
cpus | string | "" | CPU Limit — Container CPU limit, e.g. 0.5 or 2.0. Defaults to 1.0. |
env | object | Environment Variables — KEY=VALUE format, one per line. Keys starting with HEGEMONY_ are reserved and ignored. Prefer Secrets for sensitive values: environment variables are visible in the sandbox's container metadata. | |
egress_mode | string | "" | Egress policy mode — Outbound firewall for this step's container: 'open' allows everything except Deny rules, 'allow-listed' allows only Allow rules (minus Deny), 'deny-all' blocks all network access. Leave empty to inherit the flow's network policy. |
egress_allow | array of string | Egress allow rules — One rule per line, used with allow-listed mode: CIDR[:port[-port]][/tcp|udp] or service:port. | |
egress_deny | array of string | Egress deny rules — One rule per line, same format as Allow rules. Deny always wins. | |
mounted_files | array of string, or empty | null | Attachments — Which flow attachments are copied into the container under /attachments. Leave at All to copy every attachment; a selector ending in / includes that folder recursively. |
playbook | string | Playbook — Path of the playbook among the flow attachments, e.g. site.yml or ansible/site.yml. It runs from its own folder, so roles/, group_vars/ and ansible.cfg next to it are picked up. (required) | |
limit | string | "" | Limit — Optional host pattern passed to --limit, e.g. a group name or host name. |
check_mode | boolean | false | Check mode (dry run) — Run with --check: report what would change without changing anything. Combine with Show differences to review changes before approving a real run. |
diff | boolean | false | Show differences — Run with --diff so changed files and configuration show before/after. |
tags | array of string | Tags — Only run tasks with these tags (--tags), one per line. | |
skip_tags | array of string | Skip tags — Skip tasks with these tags (--skip-tags), one per line. | |
extra_vars | object | Extra variables — NAME=value, one per line, passed as extra variables (highest precedence). Values may use templates such as {{ inputs.service }}; Ansible reads the result as plain text and does not template it again. | |
secrets | object | Secrets — NAME=secret reference, one per line: a {{ secret('...') }} template or a bare reference such as vault://orgs/acme/secrets/db/password. Each becomes the Ansible variable NAME, passed from a file (never an environment variable or argument) and redacted from output. | |
group_secrets | object | Group secrets — GROUP:NAME=secret reference, one per line: the variable NAME for hosts in inventory group GROUP only, e.g. site_emea:api_key=vault://… | |
vault_password | string | "" | Ansible Vault password — Secret reference holding the password for files encrypted with ansible-vault, so existing repositories run unchanged. |
vault_ids | object | Ansible Vault IDs — LABEL=secret reference, one per line, for playbooks that use several vault IDs (--vault-id LABEL@…). | |
inventory_scope | enum: step, run | "step" | Inventory scope — 'step' puts the step's target devices in the inventory; 'run' puts every device the run targets, grouped by role, so plays can reach other roles. |
group_by | array of string | Inventory groups — Which groups to derive: role (the flow's role names), platform (platform_ios_xe), site (site_emea, site_emea_nl, …), tag (tag_env_prod), provider (provider_netbox_main). | |
extra_inventory | array of string | Extra inventory files — Attachment paths of further inventory sources layered on the generated one (-i), one per line. | |
device_credentials | boolean | true | Use device credentials — Give Ansible each device's login from its access configuration. Turn off when the playbook brings its own credentials. |
host_key_checking | enum: accept_new, strict, off | "accept_new" | Host key checking — accept_new trusts a host's key on first contact within the run and rejects a change; strict needs the keys in the image's known_hosts; off disables checking. |
requirements_file | string | "" | Requirements file — Attachment path of a requirements.yml to install with ansible-galaxy before the play (roles and collections). Needs network access to the Galaxy server. |
forks | integer, or empty | null | Forks — How many hosts Ansible works on in parallel (--forks). Unset, the playbook's ansible.cfg decides (Ansible's default is 5). |
verbosity | integer | 0 | Verbosity — Ansible verbosity: 0 is normal, 1-4 add -v to -vvvv. |
image | string | "ghcr.io/hegemony-sh/ansible-runner:0.46" | Execution image — Container image with ansible-playbook and the collections the playbook needs. Any Ansible execution environment image works. |
cache_image | boolean | true | Cache image — Keep a copy of the pulled image in the platform registry, under this organization, and use it on later runs. A tag is still checked against the image's registry by digest, and the copy serves when that registry is unreachable. Turn off for an image that must come straight from its registry every time. No effect when the platform runs no registry. |
container.build
Build Image · category: Actions · kinds: ACTION, EXECUTE
Build a container image from the flow's attachments on the Docker-in-Docker sandbox and push it to the organization's namespace of the platform registry, or to another registry; without a platform registry, keep it in the sandbox.
| Key | Type | Default | Description |
|---|---|---|---|
image | string | Image name — A name such as tools/netbox-sync goes under this organization's namespace (registry.hegemony.internal/orgs/ORG/tools/netbox-sync): pushed to the platform registry when the platform runs one, otherwise built into the sandbox only. A name with its registry in front, such as ghcr.io/acme/netbox-sync, is pushed there with the organization's saved login for that registry. Lowercase, without a tag. (required) | |
tags | array of string | Extra tags — Tags to give the image besides run-SHORT_RUN_ID, which every build gets; one per line, e.g. latest or {{ inputs.version }}. | |
context_dir | string | "" | Build context folder — Folder among the flow attachments to build from, e.g. images/netbox-sync. Leave empty for the attachments root. Only the files under it are sent to the build. |
dockerfile | string | "Dockerfile" | Dockerfile — Path of the Dockerfile inside the build context folder. |
cache_base_images | boolean | true | Cache base images — Build on copies of the Dockerfile's base images (FROM and COPY --from) kept in the platform registry under this organization, saving a copy on first use, as Cache image does for a container step. A tag is still checked against the image's registry by digest, and the copy serves when that registry is unreachable. Turn off for base images that must come straight from their registries every time. No effect when the platform runs no registry, or when the build targets another platform. |
build_args | object | Build arguments — NAME=value, one per line, for the Dockerfile's ARG instructions. Values may use templates such as {{ inputs.version }}. Build arguments are recorded in the image's history: put credentials in Build secrets instead. | |
secrets | object | Build secrets — ID=secret reference, one per line (a {{ secret('...') }} template or a bare reference such as vault://orgs/acme/secrets/pypi/token). A RUN instruction reads one with --mount=type=secret,id=ID (at /run/secrets/ID); it never lands in a layer, the image's history or the build's command line, and is redacted from the log. | |
target | string | "" | Target stage — Build only up to this stage of a multi-stage Dockerfile (--target). |
platform | string | "" | Platform — Platform to build for, e.g. linux/arm64. Leave empty for the sandbox's own. Another architecture needs emulation (QEMU) registered on the sandbox host. |
labels | object | Labels — KEY=value image labels, one per line, e.g. org.opencontainers.image.source=https://git.example.com/netbox-sync. The step always sets org.opencontainers.image.created, sh.hegemony.run and sh.hegemony.step; keys starting with sh.hegemony. are reserved. | |
egress_mode | string | "" | Egress policy mode — Network for the build's RUN instructions: they reach the network only when the effective policy is 'open' with no Deny rules, and build without any network otherwise ('allow-listed', 'deny-all', or Deny rules). Leave empty to inherit the flow's network policy. |
egress_allow | array of string | Egress allow rules — One rule per line, used with allow-listed mode: CIDR[:port[-port]][/tcp|udp] or service:port. A build cannot be held to them, so it gets no network at all. | |
egress_deny | array of string | Egress deny rules — One rule per line, same format as Allow rules. Any Deny rule takes the build's network away entirely. |
container.run
Run Container · category: Actions · kinds: ACTION, EXECUTE
Run a command inside a Docker container on the Docker-in-Docker sandbox.
| Key | Type | Default | Description |
|---|---|---|---|
image | string | Docker Image — Full image reference including tag (e.g., registry.example.com/tools:v1) (required) | |
cache_image | boolean | true | Cache image — Keep a copy of the pulled image in the platform registry, under this organization, and use it on later runs. A tag is still checked against the image's registry by digest, and the copy serves when that registry is unreachable. Turn off for an image that must come straight from its registry every time. No effect when the platform runs no registry. |
command | array of string | Command — Shell script lines joined with newlines under set -e. With no entrypoint override, the handler appends sh -c <script>; with entrypoint /bin/sh, it passes -c <script> to that shell. Leave empty to add no script. | |
entrypoint | string / array of string, or empty | null | Entrypoint override — Optional Docker --entrypoint. Leave empty to use the image entrypoint. Set /bin/sh for tool images such as hashicorp/terraform so Command runs as a shell script. Advanced YAML may use list form, e.g. ["/usr/bin/env", "bash", "-lc"]. |
working_dir | string | "/workspace" | Working Directory — Working directory inside the container (default: /workspace) |
timeout_seconds | integer, or empty | null | Timeout (seconds) — Max execution time in seconds, including the image pull. Empty: the step's timeout. A longer time raises the step's timeout to fit. |
memory | string | "" | Memory Limit — e.g., 256m, 1g |
cpus | string | "" | CPU Limit — e.g., 0.5, 2.0 |
network_disabled | boolean | false | Disable network access — Off by default to preserve Docker networking. Turn on only when this step should run with --network=none. |
network_mode | string | "" | Network mode — Optional. Use to attach to a specific Docker network (e.g. clab-mylab) or share another container's namespace (host shares the Docker-in-Docker sandbox's, not the machine's). Disabled when network access is disabled; leave empty for default Docker networking. |
attach_docker_socket | boolean | false | Attach sandbox Docker socket — Mounts the Docker-in-Docker sandbox daemon's /var/run/docker.sock into the container, giving it full control of the sandbox daemon (not the host's). Required by tools that start their own containers, like containerlab. Off by default. |
privileged | boolean | false | Run as privileged — Runs the container with --privileged, granting all capabilities and access to /proc/sys inside the Docker-in-Docker sandbox (needed by containerlab to adjust rp_filter, etc.). The sandbox itself runs privileged, so the step becomes a sandbox admin. Off by default. |
pid_mode | string | "" | PID namespace — Optional. Share the PID namespace of the Docker-in-Docker sandbox (host) or of another container (container:<name>). Required by containerlab-in-Docker so it can resolve sibling container PIDs. Leave empty for default isolation. |
extra_mounts | array of string | Extra bind mounts — One per line, format <abs-src>:<abs-dst>[:opts]. Sources resolve inside the Docker-in-Docker sandbox, not on the host. Bypasses workspace isolation; use sparingly (e.g. containerlab needs /var/run/netns shared). | |
egress_mode | string | "" | Egress policy mode — Outbound firewall for this step's container, enforced on the sandbox daemon: 'open' allows everything except Deny rules, 'allow-listed' allows only Allow rules (minus Deny), 'deny-all' blocks all network access. Leave empty to inherit the flow's network policy. Cannot be combined with host-access options or 'Disable network access'. |
egress_allow | array of string | Egress allow rules — One rule per line, used with allow-listed mode: CIDR[:port[-port]][/tcp|udp] or service:port (e.g. 172.20.30.0/24, 0.0.0.0/0:443/tcp, dind:3000). | |
egress_deny | array of string | Egress deny rules — One rule per line, same format as Allow rules. Deny always wins over Allow and is unioned with the flow policy's Deny rules. | |
env | object | Environment Variables — KEY=VALUE format, one per line. Keys starting with HEGEMONY_ are reserved and will be ignored. | |
secrets | object | Secret files — NAME=secret reference, one per line (a {{ secret('...') }} template or a bare reference such as vault://orgs/acme/secrets/db/password). Each value is written to /run/secrets/NAME inside the container and redacted from output; unlike environment variables, it never appears in the sandbox's container metadata. | |
trusted_cas | boolean | false | Trust the organization's CAs — Give the container the worker's system trust store plus the organization's trusted CAs (Settings, Trusted CAs) as a read-only file, /hegemony/ca/ca-bundle.pem, and point SSL_CERT_FILE, REQUESTS_CA_BUNDLE and CURL_CA_BUNDLE at it; NODE_EXTRA_CA_CERTS points at /hegemony/ca/org-cas.pem, the organization's CAs alone. These replace the image's own trust store, so it is off by default; a variable set in Environment Variables wins. No effect when the organization trusts no extra CA. |
mounted_artifacts | array of string, or empty | null | Artifacts — Select which upstream step artifacts are copied into the container. Leave at All to make every upstream step artifact available by default. |
mounted_step_outputs | array of string, or empty | null | Step Outputs — Select which upstream step output snapshots are copied into the container. Leave at All to make every upstream predecessor step output available by default. |
mounted_files | array of string, or empty | null | Attachments — Select which flow attachments are copied into the container under the attachments mount path. Leave at All to copy every flow attachment; a selector ending in / includes that folder recursively. |
artifacts_path | string | "" | Artifacts mount path — Absolute path inside the container where upstream step artifacts are copied. Defaults to /artifacts. |
new_artifacts_path | string | "" | New artifacts upload path — Absolute path inside the container where newly created files are harvested after the container exits: UTF-8 text files become step artifacts, and every other file is uploaded as a downloadable artifact up to the worker's per-file cap (50 MiB by default). Files the harvest drops are listed in the step's skipped-artifacts report. Defaults to /artifacts/new, or <artifacts_path>/new when you change the artifacts root. |
attachments_path | string | "" | Attachments mount path — Absolute path inside the container where attachments are copied. Defaults to /attachments. |
step_outputs_path | string | "" | Step outputs mount path — Absolute path inside the container where completed step output snapshots are copied. Defaults to /step_outputs. |
shared_path | string | "" | Shared workspace mount path — Absolute path inside the container where the shared run workspace is mounted when this step uses shared or explicit execution affinity. Defaults to /shared. |
evidence.assert
Assert · category: Checks · kinds: CHECK
Assert an expected value against evidence collected by another step.
| Key | Type | Default | Description |
|---|---|---|---|
artifact_step_id | string | Evidence Step — Only netcli.collect_evidence steps shown (required) | |
operator | enum: contains, not_contains, matches, not_matches, eq, ne, gt, lt, ge, le | "contains" | Operator — How the artifact content is compared with the expected value. Regex operators treat the expected value as a regular expression; ordering operators compare numbers and fail when either side is not a number. Defaults to Contains. |
match_scope | enum: output, lines | "output" | Match Scope — 'Whole output' asserts once against the entire artifact; 'Every line' asserts the operator against each selected line (e.g. every OSPF neighbor row must contain 'Full'). |
line_filter | string | "" | Line Filter (regex) — With 'Every line' scope: only lines matching this regex are asserted, so headers and blanks don't count. Empty selects every non-empty line. |
min_lines | integer | 1 | Minimum Lines — With 'Every line' scope: fail unless at least this many lines were selected — an empty selection must not pass vacuously. |
target_role | string | "" | Evidence Output — Choose a target and command from the selected evidence step. |
command | string | "" | Evidence Command — The command whose collected output is asserted; the editor's evidence-output picker sets it together with the Evidence Output target. Each device bound to the target is checked against the artifact the evidence step stored for that device and this command. |
expected | string | "" | Expected Value / Pattern — The value compared against the artifact content: literal text for the contains and equality operators, a regular expression for the regex operators, or a number for the ordering operators. |
message | string | "" | Custom Message (optional) — Shown verbatim as the step summary when the assertion passes and as the error when it fails, replacing the generated messages. Leave empty to get an auto-generated message that names the operator and expected value. |
evidence.compare
Compare Evidence · category: Checks · kinds: CHECK
Diff evidence artifacts between two steps (precheck vs postcheck).
| Key | Type | Default | Description |
|---|---|---|---|
precheck_step_id | string | "" | Precheck Step — Select the step that collected pre-change evidence |
postcheck_step_id | string | "" | Postcheck Step — Select the step that collected post-change evidence |
comparison_type | enum: exact, changed, subset, superset, json_diff | "exact" | Comparison mode — What a difference between the pre- and post-check evidence means. 'exact': pass only when they are identical — a difference FAILS the step (drift / no-change checks). 'changed': pass only when they differ — a difference SUCCEEDS the step (confirm an intended change actually took effect). 'subset': pass when every precheck line (or list item, or dict key and value) is still in the postcheck. 'superset': as subset, and the postcheck adds at least one. 'json_diff': parse JSON text on both sides and compare the structures; output that is not JSON must match exactly. |
artifact_name | string | "" | Only this artifact — Compare a single artifact by its exact name (e.g. 'dc1-core-01:show running-config'). Leave blank to compare every precheck artifact with its postcheck pair. |
artifact_name_pattern | string | "" | Only artifacts matching — Glob over artifact names (e.g. '*show running-config') so volatile outputs — routing tables, neighbor tables — can be left out of the comparison. Ignored when a single artifact name is set. |
ignore_patterns | array of string | Mask text matching — Regular expressions; every match is removed from BOTH sides before a text comparison, so volatile output — uptimes, timers, packet/byte counters — does not register as a difference while the rest of the line is kept. Matched per line (^ and $ anchor to line boundaries), e.g. ', \d\d:\d\d:\d\d,' to mask route uptimes. | |
ignore_fields | array of string | Ignore fields — Structured (dict) evidence, and JSON output in the JSON diff mode: top-level keys removed from both sides before comparing. |
flow.notify
Send Notification · category: Notifications · kinds: ACTION
Send an on-demand notification to a configured destination.
| Key | Type | Default | Description |
|---|---|---|---|
destination_id | string | Notification Destination — Where to send the notification (Slack, Teams, etc.) (required) | |
title | string | "" | Title — Notification title template, rendered by the notification renderer with the full notification context (run values, step outputs, secret()/env() helpers). Leave empty to use the shared default title template. |
message | string | "" | Message — Notification body template, rendered by the notification renderer with the full notification context (run values, step outputs, secret()/env() helpers). Leave empty to use the shared default body template. |
flow.run
Run Flow · category: Actions · kinds: ACTION, EXECUTE
Launch another committed flow as a child run.
| Key | Type | Default | Description |
|---|---|---|---|
flow_id | string | "" | Flow — UUID of the committed child flow to launch. Provide exactly one of flow_id / flow_name; leave this empty when selecting the child flow by name. |
flow_name | string | "" | Flow name — Child flow name, resolved to the newest flow at launch time — the portable alternative to flow_id for imported bundles. Provide exactly one of flow_id / flow_name. |
version | integer, or empty | null | Version — Committed version number of the child flow to run, starting at 1. Omit to launch the newest committed version at start time. |
wait_for_completion | boolean | true | Wait for completion — When enabled (the default), the step polls the child run until it finishes and mirrors its result, exposing the child flow's outputs. Disable to succeed as soon as the child run is created. |
run_name | string, or empty | null | Child run name — Name given to the child run. Leave empty to derive one from the parent run's name plus a short random suffix. |
field_mappings | object | Field mappings — Values for the child flow's input fields: one entry per field id with mode default (keep the child's default), literal, or template, plus the value to pass. Managed by the run-flow editor widget. | |
target_mappings | object | Target mappings — Device binding for each child target role: mode child_default, parent_role (forwarding the devices this run bound to the given parent_role_id), or none. Managed by the run-flow editor widget. | |
poll_interval_seconds | number | 5 | Poll interval (sec) — Seconds between status checks of the child run while waiting for completion, from 1 to 60 (default 5). Ignored when the step does not wait. |
general.sleep
Sleep · category: Actions · kinds: ACTION, WAIT
Pause the flow for a fixed duration.
| Key | Type | Default | Description |
|---|---|---|---|
duration_seconds | integer | 30 | Duration (seconds) — How many seconds the flow pauses at this step before moving on. Must be at least 1; defaults to 30. |
message | string, or empty | null | Message (optional) — Note recorded as the step summary and in the sleep evidence, e.g. why the flow is waiting. When omitted, a generated 'Sleeping for N seconds' text is used. |
http.request
HTTP Request · category: Actions · kinds: ACTION
Send an HTTP(S) request with any method, headers, body and authentication, and return the response for later steps.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | URL — Address the request goes to, starting with https:// or http://, such as https://api.example.com/v1/items. May use templates such as {{ inputs.base_url }}/items. Credentials never go in the URL: use Authentication. (required) | |
method | enum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS | "GET" | Method — HTTP method of the request. GET, HEAD and OPTIONS send no body. Defaults to GET. |
query | object | Query Parameters — Query parameters added to the URL, NAME=value, one per line. A parameter the URL already carries is replaced. Values may use templates. | |
headers | object | Headers — Request headers, Name=value, one per line, such as Accept=application/json. Values may use templates. Put credentials in Authentication instead: a redirect to another origin drops the credentials and every header set here except Accept, Accept-Language, Content-Type and User-Agent. Host, Content-Length, Transfer-Encoding and Connection are set by the step. | |
json_body | object | null | JSON Body — Request body sent as JSON, with Content-Type application/json unless Headers set another. Text is parsed as JSON, so a template that renders JSON works, such as {"name": "{{ inputs.name }}"}. Not allowed with GET, HEAD or OPTIONS, or together with Text Body. |
text_body | string | "" | Text Body — Request body sent as written, with Content-Type text/plain; charset=utf-8 unless Headers set another. Not allowed with GET, HEAD or OPTIONS, or together with JSON Body. |
auth_type | enum: none, bearer, basic, header | "none" | Authentication — How the request authenticates: none; a bearer token (Authorization: Bearer and the secret); basic, with a username and the secret as password; or a custom header carrying the secret. Credentials go only to the URL's own scheme, host and port: a redirect elsewhere drops them. They need an https:// URL unless Allow credentials over HTTP is on. |
auth_secret | string | "" | Secret — The token or password: a secret reference such as vault://orgs/acme/secrets/api/token, a {{ secret('...') }} template, or literal text. A value resolved from a reference is redacted from the run's logs; literal text is not, so prefer a reference. |
auth_username | string | "" | Username — Username for basic authentication; it may not contain a colon. May use templates. |
auth_header_name | string | "Authorization" | Header Name — Header that carries the secret when Authentication is Custom header, such as X-API-Key. Defaults to Authorization. |
auth_prefix | string | "" | Value Prefix — Text sent before the secret in the custom header, such as 'Token ' with its trailing space. Empty sends the secret alone. |
allow_insecure_auth | boolean | false | Allow credentials over HTTP — Send the Authentication credential to a plain http:// URL. Off by default, because over HTTP the token or password travels unencrypted and anyone on the network path can read it; turn on only for an internal endpoint that offers no HTTPS. |
expected_status | string | "200-299" | Expected Status — Comma-separated status codes and ranges that count as success, such as 200-299,304. Defaults to 200-299. With pagination every page must match. |
request_timeout_seconds | integer | 30 | Timeout (sec) — Time limit for each request, in seconds: connecting, sending and reading the whole response. Redirect hops and pages each get their own. Defaults to 30; 1 to 600. |
follow_redirects | boolean | false | Follow redirects — Follow 3xx redirects, at most 10, and report the final response. Off by default, when the redirect response itself is the result. Every hop is checked against the egress policy, and a redirect to a scheme other than http or https, or one that would send the request body to another origin, is refused. |
verify_tls | boolean | true | Verify TLS certificate — Validate the server's certificate on HTTPS requests. Turn off only for test endpoints with self-signed certificates, and prefer CA Bundle. On by default. |
ca_bundle | string | "" | CA Bundle — PEM certificates to trust for this request instead of the public certificate authorities and the organization's trusted CAs, which pins them: the PEM text, a secret reference, or a {{ secret('...') }} template. Empty trusts the public authorities plus the organization's trusted CAs (Settings, Trusted CAs). Ignored when Verify TLS certificate is off. |
max_response_bytes | integer | 1048576 | Max Response Size (bytes) — Largest response body the step reads, in bytes, summed over all pages. A larger response fails the step instead of being cut short. Defaults to 1048576 (1 MiB); at most 16777216 (16 MiB). |
extract | object | Extract — Values to pick from the JSON response, NAME=path one per line, such as id=results[0].id. A path is keys separated by dots, [n] for list items (negative counts from the end), and an optional leading $. A missing value is null. Later steps read them as steps.<id>.output.extracted.NAME. | |
sensitive | boolean | false | Sensitive response — Treat the response as secret: its body, data and extracted values stay out of the output and evidence, which keep the status, headers, size and SHA-256 of the body. Off by default. |
paginate_next | string | "" | Next Page Path — Path of the next page's URL in each JSON response, such as next. A missing, null or empty value ends pagination. Next pages are fetched with GET, the same headers and credentials, and must stay on the first request's scheme, host and port. Needs GET, Items Path, and Max Pages above 1. |
paginate_items | string | "" | Items Path — Path of the item list in each JSON response, such as results. The output's data is the first page with this list replaced by the items of every page. |
max_pages | integer | 1 | Max Pages — Most pages fetched, the first included. 1, the default, fetches a single response; at most 100. |
inventory.sync
Sync Inventory · category: Actions · kinds: ACTION
Sync an inventory provider of the run's organization now, so later steps see what the source of truth holds, such as a device a previous step created there.
| Key | Type | Default | Description |
|---|---|---|---|
provider | string | Provider — The inventory provider to sync, by its id (netbox:primary) or its name (primary). Only providers of the run's organization are found, and only one an administrator has opened to flows ('Flows may sync this provider') may be synced. (required) | |
max_age_seconds | integer | 0 | Skip if synced within (seconds) — When the provider's last sync succeeded no longer ago than this, no sync runs and the step succeeds with status 'fresh'. 0 (the default) always syncs. |
wait_seconds | integer | 300 | Wait for a running sync (seconds) — When another sync of the provider is running, ask again every 10 seconds for up to this long, then start this step's own sync. 0 fails at once with status 'busy'. |
fail_on_partial | boolean | false | Fail on a partial sync — A partial sync brought devices and sites up to date but failed for some other object type (VLANs, say). Off (the default): the step succeeds. On: it fails. |
timeout_seconds | integer | 1800 | Timeout (seconds) — The longest the whole step may take, waiting for a running sync included. Leave room for the platform's sync deadline (15 minutes unless an administrator changed it). |
monitor.connectivity
Connectivity Monitor · category: Checks · kinds: CHECK
Continuously probe targets in the background during a flow run.
| Key | Type | Default | Description |
|---|---|---|---|
check_type | enum: dns_resolve, http_health, icmp_ping, tcp_connect | "tcp_connect" | Check Type — The kind of probe sent to each target on every sample, such as a TCP connection attempt, an ICMP echo, an HTTP health request, or a DNS lookup. Options come from the host's monitor check registry and the value is validated when the step runs. Defaults to a plain TCP connect check. |
port | integer, or empty | null | Port — TCP port probed on each target by the port-based checks such as TCP Connect and HTTP Health. When empty, HTTP Health uses 80 and the other checks 22 (SSH). Ignored by checks that do not connect to a port, such as ICMP Ping and DNS Resolve. Must be between 1 and 65535. |
interval_ms | integer | 5000 | Interval (ms) — Time between successive samples, in milliseconds. Defaults to 5000 (one sample every five seconds); minimum 100. |
schedule_mode | enum: count, duration, until_join | "count" | Schedule Mode — How the monitor decides when to stop sampling: after a fixed number of samples, after a fixed duration, or - with Until Join - when the flow engine stops it at the branch's join point. Defaults to a fixed count. |
count | integer | 10 | Count — Number of samples to take before the monitor stops on its own. Only used when Schedule Mode is Fixed Count. Defaults to 10; minimum 1. |
duration_seconds | integer | 60 | Duration (sec) — How long the monitor keeps sampling, in seconds, before it stops on its own. Only used when Schedule Mode is Duration. Defaults to 60; minimum 1. |
attempt_timeout_seconds | integer | 10 | Timeout (sec) — Per-sample time limit in seconds: how long each probe waits for an answer before giving up on that sample. Defaults to 10; minimum 1. |
url_path | string | "" | URL Path — Request path for the HTTP Health check, e.g. /health. Used only when Check Type is HTTP Health; when omitted, /health is probed. |
ping_count | integer | 3 | Ping Count — Echo requests sent to each target on every ICMP Ping sample. Used only when Check Type is ICMP Ping. Defaults to 3; must be between 1 and 10. |
socks_proxy | string | "" | SOCKS Proxy — Optional authenticated SOCKS5 proxy for the TCP-based checks (tcp_connect, http_health), so a monitor can reach targets only accessible through a bastion (e.g. a lab management subnet behind dind:1080). socks5[h]😕/[user:pass@]host:port. Not usable by icmp_ping or dns_resolve — neither ICMP nor DNS traverses a SOCKS5 CONNECT tunnel, so those checks reject a configured proxy rather than probe the wrong path. |
netbox.ipam.allocate
NetBox Allocate · category: NetBox · kinds: ACTION
Take the next free IP address, prefix, VLAN or ASN from a NetBox pool, or return what an earlier attempt already took.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | NetBox URL — Address of NetBox, without /api, such as https://netbox.example.com. May use templates such as {{ vars.NETBOX.url }}. (required) | |
token | string | API Token — NetBox API token: a secret reference such as vault://orgs/acme/secrets/netbox/token, a {{ secret('...') }} template, or literal text. A value resolved from a reference is redacted from the run's logs; literal text is not, so prefer a reference. Give the token only the permissions the flow needs. (required) | |
token_type | enum: auto, v1, v2 | "auto" | Token Type — How the token is sent. Auto, the default, sends a token starting with nbt_ as a v2 token (Authorization: Bearer, NetBox 4.5 and later) and any other as a v1 token (Authorization: Token). |
allow_insecure_auth | boolean | false | Allow token over HTTP — Send the token to a plain http:// NetBox URL. Off by default, because over HTTP the token travels unencrypted and anyone on the network path can read it; turn on only for an internal NetBox that offers no HTTPS. |
verify_tls | boolean | true | Verify TLS certificate — Validate NetBox's certificate on HTTPS. Turn off only for a test NetBox with a self-signed certificate, and prefer CA Bundle. On by default. |
ca_bundle | string | "" | CA Bundle — PEM certificates to trust for NetBox instead of the public certificate authorities and the organization's trusted CAs, which pins them: the PEM text, a secret reference, or a {{ secret('...') }} template. Empty trusts the public authorities plus the organization's trusted CAs (Settings, Trusted CAs). Ignored when Verify TLS certificate is off. |
branch | string | "" | Branch — Schema ID of a NetBox Branching branch to work in (sent as the X-NetBox-Branch header), so changes stay in the branch until it is merged. Empty works on main. Needs the netbox-branching plugin. |
request_timeout_seconds | integer | 30 | Timeout (sec) — Time limit for each request to NetBox, in seconds: connecting, sending and reading the whole response. Each page and each retry gets its own. Defaults to 30; 1 to 600. |
allocate | enum: ip_from_prefix, ip_from_range, prefix_from_prefix, vlan_from_group, asn_from_range | "ip_from_prefix" | Allocate — What to take, and from where: an IP address from a prefix or an IP range, a child prefix from a prefix, a VLAN from a VLAN group, or an ASN from an ASN range. |
pool_id | string | "" | Pool ID — NetBox ID of the prefix, IP range, VLAN group or ASN range to take from. Either this or Pool Filters. May use templates. |
pool_filters | object | Pool Filters — Filters that find the pool when Pool ID is empty, NAME=value one per line, such as prefix=10.20.0.0/24 and vrf_id=3, or name=servers for a VLAN group. They must match exactly one. | |
prefix_length | integer, or empty | null | Prefix Length — Length of the child prefix to take, such as 28. Required for a prefix. |
count | integer | 1 | Count — How many to take in one go. Defaults to 1; at most 256. |
data | object | null | Data — Fields of the new object, as JSON, such as {"status": "active", "dns_name": "web-01.example.com", "description": "web-01"}. A VLAN needs a name. Text is parsed as JSON. |
existing_filters | object | Existing Filters — Filters that find what an earlier attempt of the same work already took, such as dns_name=web-01.example.com. When they match Count objects the step returns those and takes nothing new, so a re-run does not allocate twice; when they match none it allocates. Searched within the pool for prefixes, VLAN groups and ASN ranges, within the range's VRF for IP ranges, so make them specific there. Empty always allocates. | |
changelog_message | string | "" | Change Log Message — Message recorded with the change in NetBox's change log (NetBox 4.4+). |
netbox.ipam.release
NetBox Release · category: NetBox · kinds: ACTION
Give back an IP address, prefix, VLAN or ASN by deleting it from NetBox; succeeds when it is already gone.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | NetBox URL — Address of NetBox, without /api, such as https://netbox.example.com. May use templates such as {{ vars.NETBOX.url }}. (required) | |
token | string | API Token — NetBox API token: a secret reference such as vault://orgs/acme/secrets/netbox/token, a {{ secret('...') }} template, or literal text. A value resolved from a reference is redacted from the run's logs; literal text is not, so prefer a reference. Give the token only the permissions the flow needs. (required) | |
token_type | enum: auto, v1, v2 | "auto" | Token Type — How the token is sent. Auto, the default, sends a token starting with nbt_ as a v2 token (Authorization: Bearer, NetBox 4.5 and later) and any other as a v1 token (Authorization: Token). |
allow_insecure_auth | boolean | false | Allow token over HTTP — Send the token to a plain http:// NetBox URL. Off by default, because over HTTP the token travels unencrypted and anyone on the network path can read it; turn on only for an internal NetBox that offers no HTTPS. |
verify_tls | boolean | true | Verify TLS certificate — Validate NetBox's certificate on HTTPS. Turn off only for a test NetBox with a self-signed certificate, and prefer CA Bundle. On by default. |
ca_bundle | string | "" | CA Bundle — PEM certificates to trust for NetBox instead of the public certificate authorities and the organization's trusted CAs, which pins them: the PEM text, a secret reference, or a {{ secret('...') }} template. Empty trusts the public authorities plus the organization's trusted CAs (Settings, Trusted CAs). Ignored when Verify TLS certificate is off. |
branch | string | "" | Branch — Schema ID of a NetBox Branching branch to work in (sent as the X-NetBox-Branch header), so changes stay in the branch until it is merged. Empty works on main. Needs the netbox-branching plugin. |
request_timeout_seconds | integer | 30 | Timeout (sec) — Time limit for each request to NetBox, in seconds: connecting, sending and reading the whole response. Each page and each retry gets its own. Defaults to 30; 1 to 600. |
resource | enum: ip_address, prefix, vlan, asn | "ip_address" | Resource — What to give back: an IP address, a prefix, a VLAN or an ASN. |
object_id | string | "" | Object ID — NetBox ID of the object to release, such as {{ steps.allocate.output.id }}. Either this or Filters. |
filters | object | Filters — Filters that find the objects to release when Object ID is empty, NAME=value one per line, such as address=10.20.0.5/24 or dns_name=web-01.example.com. | |
max_objects | integer | 1 | Max Objects — Most objects Filters may match. More fails the step and releases nothing, so a filter that is too broad cannot delete a whole pool. Defaults to 1. |
missing_ok | boolean | true | Missing is OK — Succeed when nothing matches or the object is already gone, so a re-run of a clean-up passes. On by default. |
changelog_message | string | "" | Change Log Message — Message recorded with the change in NetBox's change log (NetBox 4.4+). |
netbox.render_config
NetBox Render Config · category: NetBox · kinds: ACTION
Have NetBox render the intended configuration of the target devices from their config templates, and keep it for later steps.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | NetBox URL — Address of NetBox, without /api, such as https://netbox.example.com. May use templates such as {{ vars.NETBOX.url }}. (required) | |
token | string | API Token — NetBox API token: a secret reference such as vault://orgs/acme/secrets/netbox/token, a {{ secret('...') }} template, or literal text. A value resolved from a reference is redacted from the run's logs; literal text is not, so prefer a reference. Give the token only the permissions the flow needs. (required) | |
token_type | enum: auto, v1, v2 | "auto" | Token Type — How the token is sent. Auto, the default, sends a token starting with nbt_ as a v2 token (Authorization: Bearer, NetBox 4.5 and later) and any other as a v1 token (Authorization: Token). |
allow_insecure_auth | boolean | false | Allow token over HTTP — Send the token to a plain http:// NetBox URL. Off by default, because over HTTP the token travels unencrypted and anyone on the network path can read it; turn on only for an internal NetBox that offers no HTTPS. |
verify_tls | boolean | true | Verify TLS certificate — Validate NetBox's certificate on HTTPS. Turn off only for a test NetBox with a self-signed certificate, and prefer CA Bundle. On by default. |
ca_bundle | string | "" | CA Bundle — PEM certificates to trust for NetBox instead of the public certificate authorities and the organization's trusted CAs, which pins them: the PEM text, a secret reference, or a {{ secret('...') }} template. Empty trusts the public authorities plus the organization's trusted CAs (Settings, Trusted CAs). Ignored when Verify TLS certificate is off. |
branch | string | "" | Branch — Schema ID of a NetBox Branching branch to work in (sent as the X-NetBox-Branch header), so changes stay in the branch until it is merged. Empty works on main. Needs the netbox-branching plugin. |
request_timeout_seconds | integer | 30 | Timeout (sec) — Time limit for each request to NetBox, in seconds: connecting, sending and reading the whole response. Each page and each retry gets its own. Defaults to 30; 1 to 600. |
object_type | enum: device, virtual_machine | "device" | Object Type — Render for devices (the step's target devices, or Object IDs) or for virtual machines (Object IDs only). |
object_ids | object | null | Object IDs — NetBox IDs to render for, separated by commas or lines, or a list. Empty renders for the step's target devices, which must come from a NetBox inventory provider. |
inventory_provider | string | "" | Inventory Provider — Hegemony inventory provider of the target devices, such as netbox:main, when the run's devices come from more than one NetBox. Empty: the target devices must all come from one NetBox provider, the one this step's URL points at. |
context | object | null | Extra Context — Extra template context as a JSON object, added to the object's config context for this rendering only, such as {"change": "{{ inputs.change_id }}"}. Text is parsed as JSON. |
netbox.request
NetBox Request · category: NetBox · kinds: ACTION
Get, list, create, update or delete NetBox objects, or post to a NetBox endpoint, and return the objects for later steps.
| Key | Type | Default | Description |
|---|---|---|---|
url | string | NetBox URL — Address of NetBox, without /api, such as https://netbox.example.com. May use templates such as {{ vars.NETBOX.url }}. (required) | |
token | string | API Token — NetBox API token: a secret reference such as vault://orgs/acme/secrets/netbox/token, a {{ secret('...') }} template, or literal text. A value resolved from a reference is redacted from the run's logs; literal text is not, so prefer a reference. Give the token only the permissions the flow needs. (required) | |
token_type | enum: auto, v1, v2 | "auto" | Token Type — How the token is sent. Auto, the default, sends a token starting with nbt_ as a v2 token (Authorization: Bearer, NetBox 4.5 and later) and any other as a v1 token (Authorization: Token). |
allow_insecure_auth | boolean | false | Allow token over HTTP — Send the token to a plain http:// NetBox URL. Off by default, because over HTTP the token travels unencrypted and anyone on the network path can read it; turn on only for an internal NetBox that offers no HTTPS. |
verify_tls | boolean | true | Verify TLS certificate — Validate NetBox's certificate on HTTPS. Turn off only for a test NetBox with a self-signed certificate, and prefer CA Bundle. On by default. |
ca_bundle | string | "" | CA Bundle — PEM certificates to trust for NetBox instead of the public certificate authorities and the organization's trusted CAs, which pins them: the PEM text, a secret reference, or a {{ secret('...') }} template. Empty trusts the public authorities plus the organization's trusted CAs (Settings, Trusted CAs). Ignored when Verify TLS certificate is off. |
branch | string | "" | Branch — Schema ID of a NetBox Branching branch to work in (sent as the X-NetBox-Branch header), so changes stay in the branch until it is merged. Empty works on main. Needs the netbox-branching plugin. |
request_timeout_seconds | integer | 30 | Timeout (sec) — Time limit for each request to NetBox, in seconds: connecting, sending and reading the whole response. Each page and each retry gets its own. Defaults to 30; 1 to 600. |
action | enum: get, list, create, update, delete, post | "get" | Action — What to do: get one object, list objects, create, update or delete objects, or post to an endpoint (a route such as render-config or available-ips). Defaults to get. |
endpoint | string | Endpoint — REST path of the objects, after /api/, such as dcim/devices, ipam/ip-addresses or plugins/<plugin>/<objects>. May use templates. (required) | |
object_id | string | "" | Object ID — NetBox ID of the object: required to update, delete or post to one object; for get, either this or Filters. Empty with a list in Data updates or deletes those objects in bulk. May use templates such as {{ steps.lookup.output.id }}. |
route | string | "" | Route — Path after the object (or after the endpoint), such as render-config, available-ips or trace. Required to post. |
filters | object | Filters — Query filters, NAME=value one per line, such as name=web-01 or tag=managed; a list repeats the filter (tag: [a, b]). For get without an Object ID they must match exactly one object. Values may use templates. limit and offset are set by the step. | |
data | object | null | Data — The object to create, the fields to change, or what to post, as JSON: an object, or a list for many objects at once (each with its id to update or delete). Text is parsed as JSON, so a template that renders JSON works, such as {"status": "active", "description": {{ inputs.note | tojson }}}. |
changelog_message | string | "" | Change Log Message — Message recorded with the change in NetBox's change log (NetBox 4.4 and later), such as the run's URL. Sent with create, update and delete. |
missing_ok | boolean | false | Missing is OK — For get and delete: succeed when the object does not exist (output found is false) instead of failing. Off by default. |
max_results | integer | 1000 | Max Results — Most objects list returns, fetched in pages of up to 1000. Defaults to 1000; at most 100000. |
expected_status | string, or empty | null | Expected Status — Status codes and ranges that count as success, such as 200-299. Empty uses the action's own: 200 for get, list and update, 201 for create, 204 for delete, 200-299 for post. |
extract | object | Extract — Values to pick from the result, NAME=path one per line, such as primary_ip=primary_ip4.address. Paths start at the object (get, create, update, post) or at the list of objects (list, and many objects at once: [0].id). A missing value is null. Later steps read steps.<id>.output.extracted.NAME. | |
max_response_bytes | integer | 4194304 | Max Response Size (bytes) — Largest response the step reads, in bytes, summed over pages and retries. Defaults to 4194304 (4 MiB); at most 16777216 (16 MiB). |
retries | integer | 2 | Retries — How often a read (get, list) is tried again while NetBox is busy or unreachable (HTTP 429, 502, 503, 504, a timeout or a dropped connection). Writes are never repeated: NetBox may already have made the change. Defaults to 2; at most 5. |
netcli.collect_evidence
Collect Evidence · category: Checks · kinds: CHECK
Capture CLI command outputs from devices as evidence.
| Key | Type | Default | Description |
|---|---|---|---|
allow_legacy_ssh | boolean | false | Allow legacy SSH algorithms — Enable weak SSH algorithms and small host or login keys for older devices, including the jump host, for every device this step connects to. To allow them for one old device only, set allow_legacy_ssh in that device's SSH access configuration instead. Host-key verification remains enabled. Use only on trusted networks while upgrading the device. |
commands | array of string | Commands (one per line) — Device CLI commands whose outputs are captured as evidence, one artifact per command per device. Use {{ variable }} syntax for flow inputs. Leave empty to collect nothing (the step still succeeds). | |
max_parallel_devices | integer | 1 | Max Parallel Devices — Devices processed concurrently (1 = sequential) |
command_timeout_seconds | integer | 30 | Command timeout (seconds) — How long one command may run on a device before it fails. Raise it for slow commands such as show tech-support. The step timeout must still cover every command on every device. Defaults to 30 seconds. |
netcli.execute
Execute CLI · category: Actions · kinds: ACTION
Run CLI commands on target devices.
| Key | Type | Default | Description |
|---|---|---|---|
allow_legacy_ssh | boolean | false | Allow legacy SSH algorithms — Enable weak SSH algorithms and small host or login keys for older devices, including the jump host, for every device this step connects to. To allow them for one old device only, set allow_legacy_ssh in that device's SSH access configuration instead. Host-key verification remains enabled. Use only on trusted networks while upgrading the device. |
commands | array of string | Commands (one per line) — Use {{ variable }} syntax for flow inputs | |
prompts | array of object | Answers to questions — Questions a command may ask before the device prompt returns, and what to answer, such as the 'Delete filename [x]?' and '[confirm]' of a delete. Each entry names the commands it applies to by a pattern, and answers once per command unless it repeats. Only listed questions are answered; any other fails the command with the line the device is waiting at. Applies to commands run at the exec prompt, not to configuration lines. | |
max_parallel_devices | integer | 1 | Max Parallel Devices — Devices processed concurrently (1 = sequential) |
command_timeout_seconds | integer | 30 | Command timeout (seconds) — How long one command, or one configuration line, may run on a device before it fails. The step timeout must still cover every command on every device. Defaults to 30 seconds. |
netcli.file_download
Download File to Device · category: Actions · kinds: ACTION
Have each target network device download a file-repository file over HTTP(S), through a short-lived link.
| Key | Type | Default | Description |
|---|---|---|---|
allow_legacy_ssh | boolean | false | Allow legacy SSH algorithms — Enable weak SSH algorithms and small host or login keys for older devices, including the jump host, for every device this step connects to. To allow them for one old device only, set allow_legacy_ssh in that device's SSH access configuration instead. Host-key verification remains enabled. Use only on trusted networks while upgrading the device. |
file | object / array of object / string, or empty | null | File — The file each target downloads. Pick a file from a file repository, or reference a run-form field such as {{ inputs.firmware }}. |
file_ids | array of string | File by id (legacy) — The file each target downloads, by its id, as older flows store it. Leave empty when File is set. | |
dest_fs | string | "flash:" | Destination — Where the file goes on the target: a device filesystem with its colon (flash:, bootflash:), or a directory on a server (/var/tmp). Defaults to "flash:". |
dest_filename | string | "" | Destination Filename — File name on the target. Leave empty to keep the stored file's name. |
transfer_timeout_seconds | integer | 3600 | Transfer timeout (seconds) — How long one target's download may take before it fails. The step timeout must still cover every target. Defaults to one hour. |
max_parallel_devices | integer | 1 | Max Parallel Devices — Targets downloading concurrently (1 = sequential) |
probe.connectivity
Connectivity Check · category: Checks · kinds: CHECK
One-shot connectivity probes (TCP/ICMP/HTTP/DNS) against targets.
| Key | Type | Default | Description |
|---|---|---|---|
check_type | enum: dns_resolve, http_health, icmp_ping, tcp_connect | "tcp_connect" | Check Type — Which probe to run against each target; the list comes from the checks registered on the worker. Defaults to a TCP connection attempt (tcp_connect) on the configured port. |
port | integer, or empty | null | Port — Port the port-based checks connect to. When empty, HTTP Health uses 80 and the other checks 22. Ignored by ICMP Ping and DNS Resolve. |
attempt_timeout_seconds | integer | 10 | Timeout (sec) — Time limit for each probe attempt, in seconds. An attempt that does not complete in time counts as failed. Defaults to 10. |
attempts | integer | 1 | Attempts — Number of attempts (1-10) |
url_path | string | "" | URL Path — URL path requested by the HTTP Health check; when omitted the check requests /health. Ignored by every other check type. |
hostname | string | "" | Hostname to Resolve — DNS name the DNS Resolve check looks up with the worker's system resolver, once per target; the target is not asked. When empty, each target's own name is looked up, so an IP address target needs this field. An IP address here fails the check, as the resolver returns it without a lookup. Ignored by every other check type. |
socks_proxy | string | "" | SOCKS5 Proxy — Route TCP-based checks through an authenticated SOCKS5 proxy (socks5[h]😕/user:pass@host:port), e.g. the lab bastion. icmp_ping rejects it — use tcp_connect for tunneled targets. |
max_parallel_devices | integer | 10 | Max Parallel Devices — Targets checked at the same time (1 = one after another). Defaults to 10. |
probe.dns
DNS Check · category: Checks · kinds: CHECK
Resolve a DNS name (or each target's hostname) and assert the answers.
| Key | Type | Default | Description |
|---|---|---|---|
query_name | string | "" | Name to Resolve — Leave empty to resolve each target device's hostname |
record_type | enum: A, AAAA, CNAME, MX, NS, TXT | "A" | Record Type — Which kind of DNS record to query for. Defaults to A records. |
resolver | string | "" | Resolver (optional) — Nameserver IP address, asked on port 53 under the flow's network policy; empty uses the system resolver |
expected_values | array of string | Expected Values (optional) — One per line; every listed value must appear in the answers | |
attempt_timeout_seconds | integer | 5 | Timeout (sec) — Overall time budget for each resolution attempt, in seconds. A lookup that has not answered in time counts as a failed attempt. Defaults to 5. |
attempts | integer | 1 | Attempts — Number of attempts (1-10) |
max_parallel_devices | integer | 10 | Max Parallel Devices — Targets looked up at the same time (1 = one after another). Defaults to 10. |
probe.http
HTTP Check · category: Checks · kinds: CHECK
Request an HTTP(S) endpoint on each target and assert status/body.
| Key | Type | Default | Description |
|---|---|---|---|
scheme | enum: http, https | "http" | Scheme — Whether the request uses plain HTTP or TLS-protected HTTPS. Also selects the default port (80 or 443) when Port is left empty. |
port | integer, or empty | null | Port — Defaults to 80/443 by scheme |
path | string | "/" | Path — Request path on the target, such as /health. A missing leading slash is added automatically, and an empty value requests the root path /. |
method | enum: GET, HEAD, POST | "GET" | Method — HTTP request method to send. Defaults to GET; note that a HEAD response has no body for the Body Contains assertion to match. |
expected_status | string | "200-399" | Expected Status — Comma-separated status codes and ranges, e.g. 200-299,301 |
body_contains | string | "" | Body Contains (optional) — Fail unless the response body contains this text |
verify_tls | boolean | true | Verify TLS certificate — Validate the server's TLS certificate on HTTPS checks against the public certificate authorities plus the organization's trusted CAs (Settings, Trusted CAs); turn off for devices with self-signed certificates. Enabled by default and ignored by plain HTTP checks. |
follow_redirects | boolean | true | Follow redirects — Follow HTTP redirects and assert the final response. When disabled, the redirect response itself is what Expected Status and Body Contains see. Enabled by default. |
attempt_timeout_seconds | integer | 10 | Timeout (sec) — Time limit for each request attempt, in seconds, covering connection setup and the response. Defaults to 10. |
attempts | integer | 1 | Attempts — Number of attempts (1-10) |
max_parallel_devices | integer | 10 | Max Parallel Devices — Targets requested at the same time (1 = one after another). Defaults to 10. |
probe.tls
TLS Certificate Check · category: Checks · kinds: CHECK
Read the TLS certificate endpoints serve and check expiry, chain, host name, and fingerprint.
| Key | Type | Default | Description |
|---|---|---|---|
port | integer | 443 | Port — TCP port the step's targets are checked on. Endpoints listed below carry their own port. Defaults to 443. |
sni | string | "" | Server Name (SNI) — Host name sent to the step's targets during the handshake and checked against their certificates. Leave empty to use each target's address. With a pasted certificate, the name it is checked against. |
endpoints | array of string / string | Endpoints — Further endpoints to check besides the step's targets, one per line as host:port or host:port:sni. Write IPv6 addresses in brackets, such as [2001:db8::1]:443. A template that renders a comma- or newline-separated list works too. At most 500 endpoints per step. | |
pem | string | "" | Certificate PEM — Check this certificate instead of connecting anywhere: paste PEM text with the server certificate first, then any chain certificates. Cannot be combined with targets or endpoints. |
attempt_timeout_seconds | integer | 10 | Timeout (sec) — Time limit for each connection and handshake, and for each OCSP request and download including its whole response, in seconds. Defaults to 10. |
require_reachable | boolean | true | Require reachable — Fail the step when an endpoint cannot be reached or completes no TLS handshake. Turn off to report unreachable endpoints without failing. |
min_days_left | integer, or empty | null | Minimum days left — Fail the step when a certificate expires in fewer whole days than this. 0 fails only expired certificates; leave empty to never fail on expiry. |
require_valid_chain | boolean | false | Require valid chain — Fail the step when a certificate does not chain to a trusted CA: the worker's system trust store plus the organization's trusted CAs (Settings, Trusted CAs), or only the CA bundle when one is set. |
require_hostname_match | boolean | false | Require host name match — Fail the step when a certificate is not valid for the name it was reached by (the SNI name, or else the endpoint's host or address). |
expected_fingerprint | string | "" | Expected fingerprint — SHA-256 fingerprint every certificate must have; colons and case are ignored. A certificate with any other fingerprint fails the step. |
expected_fingerprints | object | Expected fingerprints per endpoint — host:port=fingerprint or host:port:sni=fingerprint, one per line. Overrides Expected fingerprint for the endpoints it names: an entry with a server name applies only to that name, one without to every server name on that host and port. | |
ca_bundle | string | "" | CA bundle — PEM certificates to trust instead of the worker's system store and the organization's trusted CAs when validating chains, which pins them, or a secret reference holding them (a bare reference or a secret() template). Empty trusts the system store plus the organization's trusted CAs. |
check_ocsp | boolean | false | Check OCSP — Ask each certificate's OCSP responder whether it has been revoked. Needs the worker to reach the responder named in the certificate. |
require_ocsp_good | boolean | false | Require OCSP good — With Check OCSP on, fail the step unless the responder reports every certificate good (revoked, unknown, or no answer fails). |
check_crl | boolean | false | Check CRL — Download each certificate's certificate revocation list (CRL) from the address the certificate names and look the certificate up in it. Needs the worker to reach that address. |
require_crl_good | boolean | false | Require CRL good — With Check CRL on, fail the step unless a current CRL signed by the issuer leaves every certificate off (revoked, a stale or unverifiable list, or no list fails). |
warn_days | array of integer | Warning windows (days) — Day counts, one per line, for the expiry counters in the output summary (warn_30 counts certificates with fewer than 30 days left). They never fail the step. | |
include_pem | boolean | false | Include certificate PEM — Add each served certificate as PEM text to the step output, for later steps that store or compare it. |
max_parallel_devices | integer | 10 | Max Parallel Devices — Endpoints checked at the same time (1 = one after another). Defaults to 10. |
probe.wait_reachable
Wait Reachable (Stable) · category: Checks · kinds: WAIT
Wait until targets stay reachable for a stability window.
| Key | Type | Default | Description |
|---|---|---|---|
check_type | enum: dns_resolve, http_health, icmp_ping, tcp_connect | "tcp_connect" | Check Type — Which probe each poll runs against each target; the list comes from the checks registered on the worker. Defaults to a TCP connection attempt (tcp_connect). |
port | integer, or empty | null | Port — Port the port-based checks connect to. When empty, a device is polled on its management port (22 when the inventory sets none), an IP target on 22, and HTTP Health uses 80. Ignored by ICMP Ping and DNS Resolve. |
max_wait_seconds | integer | 300 | Max Wait (sec) — Overall deadline for the wait, in seconds. The step fails once this much time passes without every target completing its stability window. Defaults to 300. The step's timeout is raised to cover it. |
stable_seconds | integer | 30 | Stable (sec) — How long every target must remain continuously reachable before the step succeeds, in seconds; must be shorter than Max Wait (sec). A target that goes unreachable restarts its window from zero. Defaults to 30. |
poll_interval_seconds | integer | 5 | Poll Interval (sec) — Seconds to wait between reachability polls. Defaults to 5. |
connect_timeout_seconds | integer | 5 | Connect Timeout (sec) — Time limit for each poll of a target, in seconds. A target that does not answer in time counts as unreachable for that poll. Defaults to 5. |
url_path | string | "" | URL Path — URL path requested by the HTTP Health check; when omitted the check requests /health. Ignored by every other check type. |
socks_proxy | string | "" | SOCKS5 Proxy — Route TCP-based checks through an authenticated SOCKS5 proxy (socks5[h]😕/user:pass@host:port), e.g. the lab bastion. icmp_ping rejects it — use tcp_connect for tunneled targets. |
max_parallel_devices | integer | 10 | Max Parallel Devices — Targets polled at the same time (1 = one after another). Defaults to 10. |
secret.write
Write Secret · category: Actions · kinds: ACTION
Store files from the run's shared workspace or values in the organization's secret store, swap two secrets, or delete one.
| Key | Type | Default | Description |
|---|---|---|---|
operation | enum: write, swap, delete | "write" | Operation — write stores keys at Secret path; swap exchanges the keys of Secret path and Swap with; delete removes the secret at Secret path. |
path | string | Secret path — Path of the secret under the organization's own secret root, e.g. certs/web: segments of letters, digits, '_', '.', '-' joined by '/', no leading '/', no segment starting with '.'. The platform decides the backend and refuses paths outside the prefixes the organization allows steps to write. (required) | |
files | object | Keys from files — KEY=file, one per line: the content of a file an earlier step wrote to the run's shared workspace becomes the key's value. Write the file as the step container saw it (/shared/out/cert.pem) or relative to the workspace (out/cert.pem). Needs shared (or explicit) execution affinity. | |
encoding | enum: base64, text | "base64" | File encoding — How a file's bytes are stored: base64 (the default) keeps any file intact, multi-line text included, in stores that change line endings; text stores the file as it is and requires UTF-8. |
values | object | Keys from values — KEY=value, one per line: a bare secret reference (vault://orgs/acme/secrets/db/password), a {{ secret('...') }} template, or a literal stored as written. A literal stays readable in the flow definition: use references for anything sensitive. | |
merge | boolean | false | Keep other keys — Off (the default): the secret holds exactly the keys written now. On: keys the secret already holds and this step does not write are kept. |
keep_previous_at | string | "" | Keep previous values at — Optional secret path that receives the secret's current keys before they are overwritten (replacing what that path held), e.g. certs/web-previous. Nothing is copied when Secret path holds no secret yet. Must differ from Secret path. |
delete_source_files | boolean | true | Delete source files — After a successful write, overwrite each source file with zeros and delete it from the shared workspace. Best effort, not a secure wipe. |
swap_with | string | "" | Swap with — Path of the other secret, under the organization's secret root. Both secrets must exist; each ends up holding the other's keys. |
missing_ok | boolean | true | Succeed when absent — On (the default): deleting a secret that does not exist succeeds. Off: the step fails when there is nothing to delete. |
shell.execute
Execute Shell · category: Actions · kinds: ACTION, EXECUTE
Run shell commands on Linux/Unix hosts (exit codes, stdout/stderr).
| Key | Type | Default | Description |
|---|---|---|---|
allow_legacy_ssh | boolean | false | Allow legacy SSH algorithms — Enable weak SSH algorithms and small host or login keys for older devices, including the jump host, for every device this step connects to. To allow them for one old device only, set allow_legacy_ssh in that device's SSH access configuration instead. Host-key verification remains enabled. Use only on trusted networks while upgrading the device. |
commands | array of string | Commands (one per line) — Each line runs as its own exec-channel command with its own exit code. A {{ }} value must end with | quote and stand outside quotes, e.g. systemctl restart {{ inputs.service | quote }}, or come in through Environment Variables. With pwsh, values only come in through Environment Variables. | |
shell | enum: default, sh, bash, pwsh | "default" | Interpreter — How commands are wrapped on the remote host |
env | object | Environment Variables — KEY=VALUE per line, quoted and set for every command, which reads them as "$KEY" ($env:KEY with pwsh). The safe way to pass run inputs or step results. Names are letters, digits and _ (not starting with a digit). Values appear on the remote command line, so use secrets elsewhere. | |
fail_fast | boolean | true | Stop on first failure — Skip remaining commands on a device after a non-zero exit code |
command_timeout_seconds | integer | 60 | Per-command timeout (sec) — Maximum time in seconds each command may run. The limit applies to every command individually, not to the step as a whole; a command that exceeds it fails the device and its remaining commands are skipped. A command also stops when the step's own timeout is about to run out. Defaults to 60 seconds. |
max_parallel_devices | integer | 1 | Max Parallel Devices — Hosts processed concurrently (1 = sequential) |
shell.file_download
Download File to Host · category: Actions · kinds: ACTION
Have each Linux/Unix host download a file-repository file with curl, through a short-lived link, and verify its checksum.
| Key | Type | Default | Description |
|---|---|---|---|
allow_legacy_ssh | boolean | false | Allow legacy SSH algorithms — Enable weak SSH algorithms and small host or login keys for older devices, including the jump host, for every device this step connects to. To allow them for one old device only, set allow_legacy_ssh in that device's SSH access configuration instead. Host-key verification remains enabled. Use only on trusted networks while upgrading the device. |
file | object / array of object / string, or empty | null | File — The file each host downloads. Pick a file from a file repository, or reference a run-form field such as {{ inputs.package }}. |
file_ids | array of string | File by id (legacy) — The file each host downloads, by its id, as older flows store it. Leave empty when File is set. | |
dest_dir | string | "/var/tmp" | Destination Directory — Directory on the host the file goes into, as an absolute path. It must exist and the login account must be able to write to it. Defaults to "/var/tmp". |
dest_filename | string | "" | Destination Filename — File name on the host. Leave empty to keep the stored file's name. |
verify_checksum | boolean | true | Verify checksum — Compare the downloaded file's SHA-256 with the stored file's before it takes its place (needs sha256sum on the host). On by default. |
transfer_timeout_seconds | integer | 3600 | Transfer timeout (seconds) — How long one host's download may take before it fails. The step timeout must still cover every host. Defaults to one hour. |
max_parallel_devices | integer | 1 | Max Parallel Devices — Hosts downloading concurrently (1 = sequential) |
tf.apply
OpenTofu/Terraform Apply · category: Actions · kinds: ACTION, EXECUTE
Apply exactly the plan a tf.plan step saved earlier in the run.
| Key | Type | Default | Description |
|---|---|---|---|
timeout_seconds | integer, or empty | null | Timeout (seconds) — Maximum run time of the container, including the image pull. Empty: the step's timeout. A longer time raises the step's timeout to fit. |
memory | string | "" | Memory Limit — Container memory limit, e.g. 512m or 2g. Defaults to 1g. |
cpus | string | "" | CPU Limit — Container CPU limit, e.g. 0.5 or 2.0. Defaults to 1.0. |
env | object | Environment Variables — KEY=VALUE format, one per line. Keys starting with HEGEMONY_ are reserved and ignored. Prefer Secrets for sensitive values: environment variables are visible in the sandbox's container metadata. | |
egress_mode | string | "" | Egress policy mode — Outbound firewall for this step's container: 'open' allows everything except Deny rules, 'allow-listed' allows only Allow rules (minus Deny), 'deny-all' blocks all network access. Leave empty to inherit the flow's network policy. |
egress_allow | array of string | Egress allow rules — One rule per line, used with allow-listed mode: CIDR[:port[-port]][/tcp|udp] or service:port. | |
egress_deny | array of string | Egress deny rules — One rule per line, same format as Allow rules. Deny always wins. | |
mounted_files | array of string, or empty | null | Attachments — Which flow attachments are copied into the container under /attachments. Leave at All to copy every attachment; a selector ending in / includes that folder recursively. |
stop_grace_seconds | integer | 120 | Stop grace period (seconds) — How long the tool gets to stop cleanly when the step is cancelled or reaches its timeout: it receives SIGTERM, lets the changes in progress finish, saves the state and releases the lock, and is killed only after this time. At a timeout the time comes out of the step's timeout (at most half of it). 0 stops the tool at once. |
secret_env | object | Secret environment — NAME=secret reference, one per line, exported to the tool's process only (provider credentials such as AWS_SECRET_ACCESS_KEY). A reference is a {{ secret('...') }} template or a bare reference such as vault://orgs/acme/secrets/aws/key. Values are redacted from output and never appear in the container's metadata. | |
plan_step | string | Plan step — The tf.plan step whose saved plan to apply. It must have run in this run. (required) | |
state_encryption_key | string | "" | State encryption key — OpenTofu only: the same secret reference the plan step used, needed to read the encrypted plan and write encrypted state. |
lock_timeout | string | "300s" | Lock timeout — How long to wait for the state lock (-lock-timeout), e.g. 300s or 5m. |
tf.plan
OpenTofu/Terraform Plan · category: Actions · kinds: ACTION, CHECK, EXECUTE
Plan an OpenTofu or Terraform configuration from the flow's attachments and report what would change; tf.apply applies the saved plan.
| Key | Type | Default | Description |
|---|---|---|---|
timeout_seconds | integer, or empty | null | Timeout (seconds) — Maximum run time of the container, including the image pull. Empty: the step's timeout. A longer time raises the step's timeout to fit. |
memory | string | "" | Memory Limit — Container memory limit, e.g. 512m or 2g. Defaults to 1g. |
cpus | string | "" | CPU Limit — Container CPU limit, e.g. 0.5 or 2.0. Defaults to 1.0. |
env | object | Environment Variables — KEY=VALUE format, one per line. Keys starting with HEGEMONY_ are reserved and ignored. Prefer Secrets for sensitive values: environment variables are visible in the sandbox's container metadata. | |
egress_mode | string | "" | Egress policy mode — Outbound firewall for this step's container: 'open' allows everything except Deny rules, 'allow-listed' allows only Allow rules (minus Deny), 'deny-all' blocks all network access. Leave empty to inherit the flow's network policy. |
egress_allow | array of string | Egress allow rules — One rule per line, used with allow-listed mode: CIDR[:port[-port]][/tcp|udp] or service:port. | |
egress_deny | array of string | Egress deny rules — One rule per line, same format as Allow rules. Deny always wins. | |
mounted_files | array of string, or empty | null | Attachments — Which flow attachments are copied into the container under /attachments. Leave at All to copy every attachment; a selector ending in / includes that folder recursively. |
stop_grace_seconds | integer | 120 | Stop grace period (seconds) — How long the tool gets to stop cleanly when the step is cancelled or reaches its timeout: it receives SIGTERM, lets the changes in progress finish, saves the state and releases the lock, and is killed only after this time. At a timeout the time comes out of the step's timeout (at most half of it). 0 stops the tool at once. |
secret_env | object | Secret environment — NAME=secret reference, one per line, exported to the tool's process only (provider credentials such as AWS_SECRET_ACCESS_KEY). A reference is a {{ secret('...') }} template or a bare reference such as vault://orgs/acme/secrets/aws/key. Values are redacted from output and never appear in the container's metadata. | |
engine | enum: opentofu, terraform | "opentofu" | Engine — opentofu (default) or terraform. The apply step uses the same one. |
source_dir | string | "" | Configuration folder — Folder among the flow attachments holding the .tf files, e.g. terraform/network. Leave empty for the attachments root. Commit its .terraform.lock.hcl. |
state | enum: managed, backend, ephemeral | "managed" | State — managed: Hegemony stores the state (encrypted, locked, versioned) under the state name; any backend block in the configuration is replaced. backend: the configuration's own backend block (S3, Azure, GCS, Consul, PostgreSQL, …), required. ephemeral: local state that lives only for this run, for tests and demos. |
state_name | string | "" | State name — Name of the managed state in this organization, e.g. network-core. Every flow and laptop using the same name shares one state (and its lock). |
hold_until_apply | boolean | false | Hold the state until apply — Keep the managed state for this run from this plan until the run applies or ends: meanwhile other runs and people cannot lock or change it, so the plan stays valid while the run waits (for an approval, say). Every other flow using the state waits that long. A plan with no changes, or one that fails, ends the hold at once. |
backend_config | object | Backend settings — KEY=value, one per line, for a partial backend block (for example bucket=…, key=…). Values may use {{ secret('...') }}; they are passed from a file, not the command line. Only for backend state. | |
vars | object | Variables — NAME=value, one per line. Values may use templates such as {{ inputs.service_name }}; a JSON list or object (["r1","r2"]) is passed as that type. | |
secret_vars | object | Secret variables — NAME=secret reference, one per line, for sensitive variables. Always passed as strings (decode a JSON secret with jsondecode() in the configuration), from a file, and redacted from output; like every variable they are stored in the saved plan, which lives only in the run's workspace. | |
var_files | array of string | Variable files — Attachment paths of .tfvars or .tfvars.json files, one per line. | |
destroy | boolean | false | Plan a destroy — Plan the destruction of every resource the state holds (-destroy). |
refresh_only | boolean | false | Refresh only — Only reconcile state with the real infrastructure (-refresh-only). |
targets | array of string | Targets — Resource addresses to limit the plan to (-target), one per line, e.g. aws_vpc.main or aws_instance.web["blue"]. | |
replace | array of string | Replace — Resource addresses to force-replace (-replace), one per line, e.g. aws_instance.web["blue"]. | |
lock_timeout | string | "300s" | Lock timeout — How long to wait for the state lock (-lock-timeout), e.g. 300s or 5m. |
state_encryption_key | string | "" | State encryption key — OpenTofu only: secret reference of a passphrase (16+ characters). State and saved plans are then encrypted by OpenTofu before they are written anywhere. |
image | string | "" | Image — Container image with the tool, run as root with a POSIX sh. Leave empty for the engine's default: ghcr.io/hegemony-sh/opentofu-runner:0.46 for OpenTofu, hashicorp/terraform at a pinned version for Terraform. |
cache_image | boolean | true | Cache image — Keep a copy of the pulled image in the platform registry, under this organization, and use it on later runs. A tag is still checked against the image's registry by digest, and the copy serves when that registry is unreachable. Turn off for an image that must come straight from its registry every time. No effect when the platform runs no registry. |
Internal handlers
These handlers are registered but hidden from the step palette; flows use them indirectly (for example through notification or monitor nodes).
| Handler | Description |
|---|---|
general.noop | Does nothing; placeholder/testing step. |