Skip to content

Require signed boot prompts in your organization

CLIAPIIntermediate~15 min

You can make your organization refuse to serve any boot prompt that a person has not signed with a passkey. Before the requirement goes on, you see the list of prompts that the next bind, chat or run would stop serving or serve from an earlier revision, as of the moment you read it. A session that is already bound keeps the prompt it was served. Switching it off needs no preview and takes one command.

You will need the CLI for this one. The organization settings page in the portal is not documented here yet, because it has not been confirmed live at the time of writing. Only a person can do this: an agent working as a worker session cannot turn the requirement on, off or read it, and neither can an App key. See Who can do this.

The requirement is an organization setting. It is not the same as the signed grant that lets one worker edit one prompt, and it does not sign anything itself. People still sign each revision, as described in Set up an AI team. For how signing and approval fit into the wider access model, see Authorization.

Who can do this

Only the organization's current ADMINs and OWNERs, signed in as themselves. Every other caller gets the same FORBIDDEN answer:

  • a worker session, including a worker session that belongs to an admin;
  • an App key or an App run;
  • someone who is not a member, including a platform admin, and a member whose role is below ADMIN;
  • a revoked member;
  • a request for an organization that does not exist.

The refusal is deliberately identical for all of them, so it does not tell a caller whether the organization exists. An impersonated session may read nothing here, and it cannot change the setting either: reading is refused with the same FORBIDDEN, and the server refuses every change from an impersonated session before it evaluates the change, with IMPERSONATION_READ_ONLY. To use these commands, stop impersonating and act as yourself, as an ADMIN or OWNER of the organization. What each command prints in that case is in Exit codes.

Switching on and off needs no passkey and no extra confirmation from the server beyond the preview described below.

Required is not the same as enforced

The server reports three values for your organization:

Value Meaning
required Your switch. true after you switch signing on.
deploymentSigns Whether this deployment ships signing at all. An operator decides that for the deployment.
enforced required and deploymentSigns. This is what is actually true.

An organization never reads as protected where it is not. If you switch the requirement on in a deployment that does not ship signing, you read required, but not enforced: nothing is refused as unsigned yet. The setting is stored, and it starts to apply the moment an operator turns signing on for the deployment.

This page makes no claim about whether hadronmemory.com ships signing today. An operator decides that, and the deploymentSigns value tells you for the deployment you are talking to. The server's public capability list shows it too: see Server capabilities.

What the preview shows

The preview lists every served compiled boot prompt that the switch would change. Each row names the App, the Agent and the worker (an install-level row, with no worker, covers chats and workers that have not customized their prompt), the revision served today, and one of three states:

State What happens to that worker or chat when signing is enforced
SIGNATURE_PENDING No older revision is both approved and signed, and the served revision's signature is pending (a first passkey's cooling-off window). Until the window ends a bind, chat or run is refused with BOOT_PROMPT_NOT_SIGNED, as for UNSIGNED_STOPS.
REVISION_CHANGES The serve falls back to an older revision that is both approved and signed. The row says which one (changesToRevSeq).
UNSIGNED_STOPS No older revision is both approved and signed, and the served revision's own signature is not pending, so a bind, chat or run is refused with BOOT_PROMPT_NOT_SIGNED.

An older approved and signed revision is looked for first: if one exists the row is REVISION_CHANGES, and the pending or missing signature only decides the state when there is none. When signing is enforced, the served revision is the latest one that is both approved and signed. Where it is not enforced, the latest approved revision is served whether or not it is signed, and the preview still shows what would change once it is. The refusal is described in Serving a boot prompt.

Some cells in the preview's two URN columns can be empty (null with --json). The worker URN is empty on an install-level row, which has no worker (see above). The Agent URN is empty when the server could not work one out. An empty cell is not an error and there is nothing for you to fill in: Hadron prints these URNs, it does not expect you to assemble them.

Two things the preview does not promise:

  • It is a snapshot, not a watch. If you switch the requirement on while the deployment does not sign, nothing is refused yet. When an operator later turns signing on, refusals can start without a fresh preview at that moment. Whenever a read says required but not enforced, read the preview again before you rely on it. Do not assume you will always see what is about to stop just before it stops.
  • An empty preview is narrow. On an enforced organization it means nothing served would change. It does not mean nothing is unsigned anywhere, and it does not mean nothing will stop later: prompts compiled and approved later must be signed too.

Read where you stand

hadron org signing get acme.com

acme.com is your organization, as an id, a URN or the root name. The output is three lines, plus a note when the requirement is on but not enforced:

required: no
enforced: no
deploymentSigns: yes

--json prints the same fields. The command passes the organization to the server as you typed it and never looks it up first, which is why an unknown organization and a non-admin both exit 8.

Preview what switching on would do

hadron org signing preview acme.com

The first page is 20 rows by default. The most the server serves in one page is 200; ask for more and you get 200. The command prints the cursor for the next page. Use --all to read every page, or --first and --after to choose a page by hand (--all cannot be combined with them). A preview changes nothing.

Switch it on

hadron org signing on acme.com

You do not run the preview first. This command reads every page of it, shows it on stderr, asks you to confirm, and only then switches on. There is no way to skip the fetch or the display. --yes skips only the confirmation prompt, and a run with no terminal and no --yes is refused with exit 2. An empty preview is still confirmed, because the switch also governs prompts compiled and approved later.

The server accepts the switch only with the token from a preview that you fetched for this organization in the last 10 minutes. The command handles that for you.

When it comes back stale

If the preview changed since you read it, or 10 minutes passed, the server answers BOOT_PROMPT_SIGNING_PREVIEW_STALE, the CLI exits 5, and nothing changes. A missing token, one from another organization or another caller, and a forged one get the same answer. The fix is always the same: run hadron org signing on acme.com again and review the current preview.

Switching on when it is already on, with a valid token, succeeds and changes nothing.

Switch it off

hadron org signing off acme.com

Its Apps may again serve boot prompts that are approved but not signed. No preview and no token are needed, and switching off an already-off switch succeeds. The command asks you to confirm; --yes skips the prompt, and a run with no terminal and no --yes is refused with exit 2.

Exit codes

Exit Meaning
1 off from an impersonated session: the server answers IMPERSONATION_READ_ONLY and the CLI prints the server's message, which says the session is read-only. Nothing changed. Stop impersonating and run it as yourself.
2 No terminal and no --yes, --all combined with --first or --after, a bad --first, or a server too old to serve the preview URN fields.
5 The preview was stale (BOOT_PROMPT_SIGNING_PREVIEW_STALE). Nothing changed. Run on again.
8 FORBIDDEN: you are not a current ADMIN or OWNER of that organization, or it does not exist. An impersonated session also gets 8 from get, preview and on, because the read, or for on the preview read, is refused first.

What you need

  • CLI 0.44.0 or later. The hadron org signing commands first shipped in 0.44.0. Check the version you have with hadron --version.
  • A server new enough for the preview. preview and on need the Agent and worker URN fields on each preview row. A server without them makes the CLI refuse with exit 2 and say the CLI and server schema versions are out of sync, before anything is sent to change; that refusal is the check. hadron server-info shows the version of the server you are talking to. The GraphQL reference has not been regenerated since those fields were added, so its preview rows do not list them yet. The regeneration is tracked in hadron-docs#719.
  • To be signed in as yourself with an organization role of ADMIN or OWNER.

The portal's organization settings section for this switch is coming. This page will describe its steps when they are confirmed live.