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.

Entities: recording what you do not automate

Not everything worth recording is something you run changes against. An entity is a minimal node with no template and no actions — a database schema, a rack, a building. It sits under a project, environment, asset or another entity, in an entities/ collection, and holds entities only. It still carries properties, settings, metadata, asset owners, maintenance windows, bookmarks and the archive / delete / restore / destroy / export lifecycle (in the GUI: the list's Show deleted view with Restore and Destroy, and Export subtree… on the node), and access is granted by path like every node. Entities are part of the core platform: no entitlement and no limit. Manage them with opschain entity against a server:

# one entity, under an environment
opschain entity create payments/environments/prod --code orders_schema --name "Orders schema"

# a batch of child entities from a YAML (or JSON) file
cat > tables.yaml <<'YAML'
items:
  - code: orders
    name: Orders
  - code: order_lines
    name: Order lines
YAML
opschain entity bulk-create payments/environments/prod/entities/orders_schema --file tables.yaml

# read them back, archive one, delete one
opschain entity list payments/environments/prod/entities/orders_schema
opschain entity show payments/environments/prod/entities/orders_schema/entities/orders
opschain entity update payments/environments/prod/entities/orders_schema/entities/order_lines --archived
opschain entity delete payments/environments/prod/entities/orders_schema/entities/order_lines --confirm

# the environment's subtree with its entities, nested, in one read
opschain nodes list payments/environments/prod --include-entities

# an entity has properties and settings like any node
opschain properties show payments/environments/prod/entities/orders_schema
opschain settings show payments/environments/prod/entities/orders_schema

# undo the delete (the shared lifecycle verbs take entity paths)
opschain admin nodes restore payments/environments/prod/entities/orders_schema/entities/order_lines

nodes list --include-entities needs a path: entities are listed under one subtree, never estate-wide.

A batch is written in sets of up to 1000 — a bigger file is split for you — and each item answers created or failed with the named reason (a taken code, a duplicate in the batch), printed as Failed <code>: <reason> while the rest are created. Every created entity records its own api:nodes:create event with kind: entity. A change cannot target an entity, and an environment or asset cannot be created under one — both are refused by name. The same operations are on the API: the v2 EntityService and the v1 node-path lane (POST /api/projects/payments/environments/prod/entities). opschain docs cli/entity is the command manual and opschain docs resources/entity the field dictionary.

When an entity grows automation, promote it; when an asset no longer needs any, demote it. Either creates a new node and leaves the old one archived (an ordinary archived node you can still edit, unarchive or delete) as the record of what it was, with an opschain_lineage entry in the new node's properties and an api:nodes:promoted / api:nodes:demoted audit event:

opschain entity promote /projects/payments/environments/prod/entities/orders_schema \
  --template postgres_schema --template-version v3
opschain asset demote /projects/payments/environments/prod/assets/legacy_db --code legacy_db_record

A demotion is refused by name while the asset still has active changes, pending approvals or schedules. A workflow or trigger aimed at the asset does not block it — as with deleting an asset — but any change it later tries to start on the old asset is refused, naming the entity it became, so retarget those workflows and triggers after demoting.

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.