Action catalog format
A catalog is a YAML document, signed as a DSSE envelope over its exact bytes (vcx catalog sign). The contract is
contract/v0/catalog.schema.json in the repository; this page summarises it.
apiVersion: catalog.vaicoa.com/v0kind: ActionCatalogmetadata: name: vaicoa-builtin version: 2026.11.9 # layers only: layer: org.team, environments: [lab, demo]actions: [ … ]playbooks: [ … ]An action
Section titled “An action”The built-in env.delete:
- type: env.delete summary: Remove a container and, if asked, its volumes — data is lost riskClass: risky destructive: true params: type: object additionalProperties: false required: [name] properties: name: {type: string, pattern: "^[a-z0-9][a-z0-9-]{0,39}$"} deleteVolumes: {type: boolean, default: false} constraints: - "params.name in state.containers" requires: minLevel: device approval: quorum: [{kind: human, count: 1, minLevel: presence, roles: [owner, operator], channels: [cli, device-app]}] ttl: 1h module: podman_env executor: {name: podman, side: node, minVersion: 0.1.0} display: title: "Delete container {params.name} in {environment}" facts: [{label: Container, value: "{params.name}"}, {label: Delete volumes, value: "{params.deleteVolumes}"}] onReject: "nothing changes; the container keeps running" confirm: "{params.name}" targets: [podman-host] controls: [change-management]| Field | Meaning |
|---|---|
type | the action’s name; layer actions live in their own namespace org.<name>.… |
summary | one line; also the tool description an agent sees |
riskClass | safe, routine or risky; decides the default policy |
destructive | the approver must also pick or type the target (display.confirm); never retried; never an emergency change |
dataAccess | a read: safe, not destructive, no quorum; counted against the read budget, redacted |
params | JSON Schema the core validates the parameters against |
constraints | CEL expressions over params, state (from the module), env, principal, now, assurance; a bare expression or {expr, message}, where the message names the fix |
requires.minLevel | the proposer’s lowest level |
requires.approval.quorum | a list of groups, each {kind: human|agent, count, minLevel, roles, channels, profile}; every group must be met; empty means no approval |
requires.approval.ttl | how long an approval stays valid |
requires.productionApproval | replaces approval in environments marked production; the node applies it from its own config |
module | the module that supplies state, preconditions and the plan |
executor | {name, side: node|hub, minVersion}: where and by what the action runs |
targets | the target kinds it applies to: podman-host, k3s-host, k3s, capi, hetzner-cloud, git, core, … |
bindings | another executor per target kind |
credential | the credential slot kind a hub-side driver gets for one call |
display | the template: title, facts, onReject, confirm; rendered on the approver’s device |
controls | optional labels such as change-management; fixed by the catalog digest in every audit record |
implements | layers only: the built-in action this one narrows (everything must be at least as strict) |
mcp | actions imported from an MCP server: {server, tool, definitionSha256}, compared on every call |
The core enforces some invariants whatever a catalog says: an approver is never the proposer, risky actions need at
least one human group at presence, and agent groups alone satisfy only safe and routine.
A playbook
Section titled “A playbook”Playbooks have the same params, constraints, requires and module, plus:
| Field | Meaning |
|---|---|
forEach | {items, max, maxParallel}: a bounded list the steps run over, for example the nodes of a cluster |
blast | {set, maxShare}: the largest share of the set one batch may touch |
steps | each {name, action, params, target, check}; parameters are templates over the playbook’s own parameters and item |
check | a read action and a CEL expression on its result, with wait and interval |
onFailure, rollback | stop (default) or a named rollback that runs at once, as part of the approved plan |
The playbook’s risk class is the highest of its steps. The approval covers the expanded plan by digest; nodes verify every step against it.
Layers
Section titled “Layers”A layer is a catalog with metadata.layer: org.<name>, signed by the team’s owners
(vcx catalog sign --layer org.<name>) and pinned in the roster. It may only add actions in its namespace or narrow a
built-in one (implements); it can never lower a risk class, shrink a quorum or swap an executor. An example lives in
the repository under examples/catalog/notify/.