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.

Where OpsChain runs: the three postures

One binary runs in three postures, and each is for something different. Every other page describes a server on PostgreSQL unless it says otherwise.

• The local lane (--local, or no server context) — the engine in your terminal, with one implicit principal, your repository's .opschain/ tree as the whole estate, its history in your opschain home's own SQLite store (<opschain home>/local/opschain.db) and its secrets in the home's local secret store (opschain secret). It is for developing actions and workflows, evaluating them before they reach a server, and CI jobs that run them (--local --approve-all -o json, the exit code as the verdict). It has no users, no audit history, no estate, no approvals and no notifications — a local run is never evidence. See opschain docs getting-started/0-2-local-mode-and-server-mode and storage.
• A server on the SQLite store (opschain server start with no store configured) — the run engine, the runner and agent fleet, licensing and the home's local secret store behind the HTTP API, with no PostgreSQL to provision. It is for development harnesses and tests: GUI development against its API, end-to-end suites, a runner-fleet playground — and it is labelled as one: it binds to loopback (127.0.0.1:8443) unless --listen or listen: says otherwise, it prints a startup notice naming the posture and the bound address, and it does not serve the GUI (the root URL answers a page saying the GUI needs PostgreSQL). It holds no users, no estate, no templates, no workflow catalog, no notifications and no governance — those families answer "PostgreSQL required" by name — so it is not a way to evaluate the estate features. See api-v2 ("the embedded SQLite store") and storage.
• A server on PostgreSQL (store: postgres://…) — the product: identity and access rules, the estate, templates, workflows, triggers, notifications, governance, the audit history and the GUI, with the fleet and the run engine underneath. The full server needs PostgreSQL; the opschain-trial Docker Compose starts PostgreSQL, the server and the GUI in one command — see storage ("Evaluating the full server") and opschain docs getting-started/0-1-install-and-sign-in.

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.
• Entities — the minimal node kind: anything worth recording in the estate (a schema, a rack, a building) with no template and no automation, so no change ever runs against one. An entity lives in an entities/ collection under a project, environment, asset or another entity and parents entities only, keeping properties, settings, metadata, owners, maintenance windows, bookmarks and the node lifecycle. Core, with no entitlement and no limit. Managed with opschain entity. See resources/entity.
• 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.