Skip to content
A personal experiment · alpha · code not public yet · no offer, no support Project status →

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/v0
kind: ActionCatalog
metadata:
name: vaicoa-builtin
version: 2026.11.9
# layers only: layer: org.team, environments: [lab, demo]
actions: [ … ]
playbooks: [ … ]

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]
FieldMeaning
typethe action’s name; layer actions live in their own namespace org.<name>.…
summaryone line; also the tool description an agent sees
riskClasssafe, routine or risky; decides the default policy
destructivethe approver must also pick or type the target (display.confirm); never retried; never an emergency change
dataAccessa read: safe, not destructive, no quorum; counted against the read budget, redacted
paramsJSON Schema the core validates the parameters against
constraintsCEL expressions over params, state (from the module), env, principal, now, assurance; a bare expression or {expr, message}, where the message names the fix
requires.minLevelthe proposer’s lowest level
requires.approval.quoruma list of groups, each {kind: human|agent, count, minLevel, roles, channels, profile}; every group must be met; empty means no approval
requires.approval.ttlhow long an approval stays valid
requires.productionApprovalreplaces approval in environments marked production; the node applies it from its own config
modulethe module that supplies state, preconditions and the plan
executor{name, side: node|hub, minVersion}: where and by what the action runs
targetsthe target kinds it applies to: podman-host, k3s-host, k3s, capi, hetzner-cloud, git, core, …
bindingsanother executor per target kind
credentialthe credential slot kind a hub-side driver gets for one call
displaythe template: title, facts, onReject, confirm; rendered on the approver’s device
controlsoptional labels such as change-management; fixed by the catalog digest in every audit record
implementslayers only: the built-in action this one narrows (everything must be at least as strict)
mcpactions 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.

Playbooks have the same params, constraints, requires and module, plus:

FieldMeaning
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
stepseach {name, action, params, target, check}; parameters are templates over the playbook’s own parameters and item
checka read action and a CEL expression on its result, with wait and interval
onFailure, rollbackstop (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.

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/.