Concepts summary

Included from Basic tier

The OpsChain vocabulary in one page: what each core concept is and where its deep page lives. Start with architecture for how the pieces compose; follow the links here for the full semantics.

The estate and its content

• Estate / nodes — everything OpsChain runs, it runs against a node: a tree of projects containing environments containing assets, each addressed by a path (/projects/web/environments/prod/assets/api). Properties, settings, authorisation, maintenance windows and artifacts all attach to nodes, so the path is the universal scoping handle. See opschain docs getting-started/1-1-projects-environments-assets-and-hosts and resources/node.
• Infrastructure nodes — the registered hosts the estate can reach: a fourth node kind living in infrastructure/ collections inside the tree, each carrying an address, an operating system and a transport-provider binding, registered and deregistered as deliberate audited acts. They have no action catalog — a change runs on an asset as always, and a host-targeted action names the host as its host_ref, the transport resolving and the caller's grant enforcing at the host's own path. See opschain docs infrastructure-nodes and opschain docs getting-started/6-4-hosts-without-a-runner.
• Git remotes & templates — a git remote is a repository a project can read; a template builds on one and pins versions (exact revisions). An asset pinned to a template version takes its action catalog from that revision, so what an asset can run is always a reviewable git fact. See opschain docs getting-started/3-3-git-remotes-and-the-identity-policy.
• Actions — the units of work, authored as YAML files in the repository. Composite actions call others with typed uses: + with: parameters, validated at compile. Action packs are git repositories of reusable actions (script:execute, terraform, ansible) mounted by name. See opschain docs getting-started/2-1-your-first-action and getting-started/2-4-using-packs.

Running work

• Changes, workflows and runs — a change runs one action against one node; a workflow is a published, versioned definition that sequences changes, stages and waits across many nodes. Starting either creates a run, the audited execution record. See resources/change and resources/workflow_run.
• Steps and the step tree — every run compiles into a tree of steps (stages, change steps, waits, fan-out expansions); the tree is the execution record, carrying each step's status, entry verdicts, retries and outputs. Roll-up status is computed by the engine on every transition. See resources/step and orchestration.
• Properties & settings — properties are your data (hosts, counts, endpoints), layered project → environment → asset into each step's merged view; settings tune OpsChain itself on the same overlay, with deployment configuration (config.yaml) winning where both speak. The converged view is the effective merge a given node sees. See opschain docs getting-started/1-3-properties-and-settings, settings and config.
• Typed inputs — workflows and top-level actions declare inputs: (string, number, boolean, enum, secret, list<string>), validated before a run exists and recorded on it; secret inputs are vault references and always mask. See orchestration.
• Expressions, when: and estate() — ${{ … }} spans are compile-checked CEL over properties.*, inputs.*, steps.* and run/node metadata; when: gates any step with a recorded verdict; estate('<path>') reads another node's converged properties, RBAC-checked and version-audited at step entry. See expressions.
• Fan-out — for_each: expands a step over a list (often an estate() enumeration) into parallel or sequential children, capped by the orchestration.fan_out_limit settings ladder. See orchestration.
• Outputs — a step publishes outputs later steps read as steps.<name>.outputs.*; a workflow change step rolls its nested run's outputs up, and a fan-out parent exposes outputs.children. See expressions.
• Error policy — on_error: fail|continue or the object form that invokes a compensating action; when: error()/always() marks handler steps the abort cascade spares (the run still finalises ERROR with error_handled recorded); retries: re-executes a failing step with persisted backoff. See orchestration.
• Approvals & gates — a wait step parks a run mid-flow for a human confirmation, made conditional with when:; governed sign-off with named approvers, quorum and audit is an approval policy (opschain docs change-governance) holding the run before it starts. The legacy step key requires_approval_from: still gates the wait and stays enforced; opschain approval-policies convert-step-gates creates the equivalent policies. See opschain docs getting-started/4-1-anatomy-and-the-step-kinds.

Automation

• Events, correlation and chains — the append-only, typed audit stream: every run and step transition and every supervised verb is an event carrying a correlation_id and chain_depth, so any event is a handle into its whole cascade (its chain). See events and resources/event.
• Triggers & scheduled activities — a trigger matches events and creates a change or workflow run in response, each match recorded exactly once as a firing; scheduled activities start runs on a cron schedule. Everything a firing causes shares the matched event's chain. See triggers.
• Maintenance windows — quiesce one node's subtree: non-allowlisted run creation refuses with a named 422 and trigger firings park as deferred until the window ends. See maintenance-windows.

The fleet

• Runners, groups and placement — a runner is the outbound-only execution client, registered into groups whose attributes placement matches against; the dispatch plane annotates every queued entry with a satisfiability verdict. See runner, runner-registry, dispatch and fleet-queue.
• Agents & trust — AI and automation agents run against OpsChain through an outbound-only tunnel under server-side trust grants; an agent can never name its own tier or waive a gate. See agent-plane.

Governance and operations

• Authorisation (RBAC) — path-based policies and rules decide every request (least-permissive ranking); a denied read renders 404, so resource existence never leaks. Managed with opschain admin authz (see opschain docs cli/admin-authz-policies); authentication is the identity plane's provider chain.
• Licence & entitlements — the embedded Basic tier plus signed licence documents resolve into the effective entitlements that answer every create and feature gate; stored envelopes re-verify on every resolution. See entitlements.
• Quiesce, backup & export — three stop postures (replica dispatch quiesce, durable system quiesce, per-plane emergency halt — see platform-halt); opschain server backup snapshots the store and blobstore, and definitions export/import keeps automation under change control. See opschain docs getting-started/8-1-backup-restore-and-prove-it.
• Artifacts — files a run stores against a node: versioned, digest-recorded, fetchable by later runs, and hand-off between runs rides the event chain. See opschain docs getting-started/3-6-artifacts and getting-started/5-7-lab-the-hand-off-pattern.
• Secrets & vault references — secret values live in the server's vault; properties, step contexts and logs carry only references, resolved the moment a step runs and masked everywhere. See opschain docs getting-started/3-5-secrets-and-the-vault.
• The GUI — the embedded web console: estate, runs and activity views plus the Operations area and a Documentation reader backed by /api/docs. See gui-operations.
• The documentation estates — this reference tree (opschain docs, /api/docs) and the getting-started guide (opschain learn, also served under getting-started/ slugs) are embedded in the binary, so they always describe the release that is running. The same set is full-text searchable at GET /api/docs/search?q=… (the ranking opschain docs search uses), and both OpenAPI documents render as a browsable API reference with sample payloads at GET /api/docs/api-reference (/v1, /v2); opschain docs export --site writes the whole publishable set per release.