The core platform — user guide

Included from Basic tier

This is the operator's guide to base OpsChain: the estate you model, the configuration that shapes work, the changes and workflows that run it, the record every run leaves behind, and where each of those lives in the GUI. It is a guide to operating the platform — the numbered getting-started runbooks (opschain learn) teach the same ground hands-on, and each section below names its runbook and reference pages.

The estate: projects, environments, assets

Everything OpsChain runs is targeted at a node in one tree: projects at the top, environments inside projects, assets inside environments — /projects/payments/environments/prod/assets/api-1. The tree is the authority for targeting (a run executes at a node), for configuration (properties and settings overlay down it), and for access control (path-based rules grant by subtree).

opschain nodes list                 # the tree, as far as you may see
opschain nodes show <path>          # one node's facts and lifecycle
opschain nodes create <path> ...    # grow it
opschain nodes update <path> ...    # maintain it

Nodes carry lifecycle, not just shape: archive a node to retire it without losing history, and let templates stamp out repeatable asset shapes. Deleting is deliberately a two-step export → delete lane so an estate object never silently disappears.

Lesson 1.1 walks this end to end; opschain docs resources/node is the field dictionary.

Properties and settings

Two document families configure work, both versioned, both edited with compare-and-set so concurrent editors conflict loudly rather than overwrite each other:

• Properties are the data your actions read (@<key> in rendered files, ${{ properties.* }} in expressions). They overlay down the tree — project → environment → asset → change — most specific wins, and a run's converged view (opschain runs converged <run-id>) shows exactly what the run saw, with per-key layer attribution.
• Settings tune platform behaviour at a node (runner selection, notification routing and similar), with the same overlay and history semantics.

opschain properties show <path>     # also: edit, history
opschain settings show <path>       # also: edit, history
opschain properties export ...      # promote a layer between estates

Lesson 1.3 covers the overlay model; opschain docs resources/properties has the document shape. Secret values never live in properties — they live in the vault and are referenced (secret-vault://<path>/<key>; lesson 3.5 and the Secrets guides).

Changes, and the approval funnel

A change is one action executed at one node — created directly, or by a workflow step. Create one, follow it, answer its gates:

opschain runs create change <node-path> --action <action> --follow
opschain runs list
opschain runs show <run-id>
opschain runs logs <run-id>         # the full log stream
opschain runs approve <run-id>      # answer a waiting gate; also: reject, continue
opschain runs retry <run-id>        # also: cancel, pause, resume

Approval comes in two strengths. With the change-governance pack licensed, a change manager imposes approval from outside: an approval policy matched by path, action and metadata holds every matching change in pending_approval before anything executes, and no workflow author can code around it. A workflow author can also ask for approval inside the run with the legacy requires_approval_from step key — still enforced, superseded by policies (opschain approval-policies convert-step-gates converts). Held changes land in the approvers' inbox (GUI: Governance → Reviews & approvals) with a checklist, prior-run evidence and quorum rules; an approved change is released, not auto-run. The change-governance guide (opschain docs getting-started/governance-approvals) walks the funnel; opschain docs change-governance is the model reference.

Runs and steps

Everything that executes — a change or a workflow — is a run made of steps. A step is the unit of truth: it has a status (pending, queued, running, waiting, success, skipped, error, cancelled — opschain docs resources/step has the full vocabulary), logs, published outputs, and artifacts it declared. Runs compose steps in order and in parallel; a failure settles the step error and the run reports exactly which step, with opschain runs retry resuming from failure rather than rerunning what succeeded. Steps execute on runners — the fleet of executors you enrol (lesson 6.1) — and the fleet queue holds work with a placement verdict when no runner currently satisfies it, visible rather than vanished.

Events and audit

Every meaningful thing the platform does emits a typed event — the estate's flight recorder:

opschain events                        # the feed, filterable by node/type/level
opschain chains show <correlation-id>  # one cascade, end to end
opschain chains triage <run-id>        # one-command root cause
opschain audit                         # the audit history, newest first

Events correlate into chains (trigger → run → emitted event → next run), so an incident reads as one story instead of scattered rows. The audit history is the governed lens over the same record: who did what, to which node, from which change — and a node's audit view encapsulates its whole subtree, so a project page answers for its environments and assets too. Lesson 5.1 teaches the feed; opschain docs events is the model reference.

The GUI, area by area

The binary serves the web interface at / — same authority, same 404-on-deny access model as the CLI. Three areas matter day to day:

• Estate — the tree as screens. Every node page leads with Activity and Chains ("what is happening here" before "what is this"), then the node-type tabs (Environments/Assets, Actions, Scheduled activity, Templates, Artifacts, Audit history), with Properties and Settings alongside. The Run form renders an action's typed inputs as a form, secrets masked.
• Governance — the control plane for oversight: Manage security, Evidence & controls, Reviews & approvals (the approvals inbox), Policies & owners, Classification, Audit history, Notifications governance and Compliance. Pack-gated destinations render greyed with the owning pack named, never hidden. Audit history lives here — it is governance's traceability spine, not an estate tab.
• Administration — the deployment itself: server and runner health, agents, licence, configuration and settings, maintenance windows, users and groups, database. Lesson 9.1 tours it panel by panel.

Everything the GUI shows deep-links (/docs/<slug>, /governance/..., /admin/...), and the docs area serves this same embedded corpus.

Where next

• The numbered runbooks: opschain learn — install to automation in 19 hands-on chapters.
• Feature guides: workflows, secrets providers, identity providers, agents, model providers, and the governance and MintPress guides — all beside this page in the docs index.
• The reference tree: opschain docs — components, data dictionary, CLI manual, concepts.