Moorhold docs

Moorhold lets agents and people who aren't admins ask for changes to the stack, without letting any of them make a change on their own. A change asked for this way is a proposal. It waits until a different person approves it, and only then does the reconciler apply it. This is the four-eyes rule: two people have looked at every change an agent or a proposer asks for before it happens.

This page explains how proposals work in the latest release (2026.11.4).

The Stack names two sets of groups in spec.agents:

  • Proposers (proposerGroups) may propose a change. So may an agent acting for one of them. On an installed server these are data-engineers and shipboard-admins.
  • Approvers (approverGroups) may approve, reject or withdraw a proposal. They're the stack's admins, and they may also apply a source change directly in the portal, without a proposal. On an installed server this is shipboard-admins.

An agent always works through a proposal. It acts as the person it signed in for, and nothing it does through the portal's MCP server changes the stack until someone approves it.

  1. Someone proposes a change: create, update or delete one resource. The proposal names the target, who proposed it and why. It holds secret references only, never a secret's value.
  2. The reconciler works out what applying it would do in each tool and attaches that as the proposal's plan. The approver sees the plan before deciding.
  3. An approver approves or rejects it in the portal, or with moorhold proposals.
  4. When it's approved, the reconciler treats the target as part of the desired state and applies it. The proposal becomes applied.
  5. An approver can withdraw it later. The reconciler then removes the change, and the proposal becomes removed.

The person who proposed it can cancel it while it's still waiting. That needs no second person, because nothing has changed.

A decided proposal can't be edited. To change it, propose again.

  • A person, at the portal. A decision has to come from a session in one of the Stack's humanClients, the portal's own sign-in. An agent's token can't decide, and nor can a session from a trusted front proxy.
  • An approver. The person must be in one of the approver groups.
  • Not your own. Nobody approves a proposal they made, or one whose target they edited.
  • Still waiting. Only a proposal that's pending_approval can be approved or rejected.

Every decision is written to the audit log as proposal.approve, proposal.reject or proposal.withdraw, with who made it and through which client.

The exception: a server with one admin

Section titled "The exception: a server with one admin"

On a server with one admin, that admin may approve their own tool upgrade or their own update to Moorhold. They confirm a tool upgrade by typing the tool's name, and an update to Moorhold by typing the version. The record says self-approved, only admin. A source proposal still cannot be approved by the person who made it. An admin can add a web service in the portal without a proposal.

Some requests the server acts on as root need no second admin, however many admins there are: adding the sample data and giving a tool more memory. The admin who asks approves it as they ask, and the audit log records "Asked for and approved by" and their name.

Setting the mail password is separate: after a fresh sign-in, one admin may set it, even when the server has more than one admin.

The one-admin exception for tool upgrades and updates ends by itself. When a second person joins the approver groups, the count is two and those need someone else's approval again.

Upgrading the tools through proposals

Section titled "Upgrading the tools through proposals"

The Stack page shows each tool against the release's manifest. When a tool can move to a newer version, an admin proposes the step there, and another admin approves it. The reconciler then changes the Component's version and records the proposal as applied. With one admin, they approve it themselves as above.

  • The portal MCP tools reference lists the tools an agent uses to follow its proposals.
  • The page on requests the server acts on explains approvals that reach root on the server.