---
template_version: 1
title: "Transfer orchestrator role"
applicable_modes: [pubkey]
default_flow: manual
---

# Hand off the orchestrator role of {{cluster_name}}

The orchestrator is the cluster member with the `coordinator` role
who issues admission tokens, approves new members, and sets the
admission policy. Transferring this role requires both the OLD and
NEW orchestrator to confirm.

## Pre-requisites

- The new orchestrator already has a member entry in
  `cluster.yaml.members[]` (i.e. they joined the cluster previously).
- The OLD orchestrator is initiating this transfer — they're the
  one who can edit `cluster.yaml`.

## Steps

### 1 · Old orchestrator (initiates)

1. From the portal Manage tab → Authorized identities → find new
   orchestrator → ⋮ → "Promote to coordinator".
   This bumps their `role` field from `participant` to `coordinator`
   in `cluster.yaml.members[]`.

2. Notify the new orchestrator:
       "I bumped you to coordinator. Confirm by running
        `meshcore agent confirm-role` on your machine."

### 2 · New orchestrator (confirms)

1. On the new machine:
       meshcore agent confirm-role
   This signs an "I accept the coordinator role" challenge with
   your pubkey, the daemon verifies, and writes
   `cluster.yaml.members[i].role_confirmed_at = today`.

2. (Optional) Issue a test admission token to confirm you have the
   coordinator's capabilities:
       meshcore admission issue-token --identity test-bot --role observer
   If this works, you're fully empowered.

### 3 · Old orchestrator (steps down, optional)

If you want to fully step down (vs. share coordinator role):

1. Manage tab → your own identity → ⋮ → "Demote to participant".
2. Add a `note:` field explaining the handoff.

## What changes

- New orchestrator can issue tokens, approve/reject, revoke members,
  edit admission policy.
- Old orchestrator (if demoted) can still operate as a member but
  cannot manage admission anymore.
- Cluster channel stays the same; no member loses access.

## Why we do it this way

Both parties sign off because:
- The OLD orchestrator could promote anyone unilaterally; the
  confirm-role step prevents accidental/forced promotions.
- The NEW orchestrator has cryptographic proof they accepted; the
  cluster's audit log records both sides.

## After the transfer

Read https://meshkore.com/cluster/operate § "Operator
responsibilities". The new orchestrator becomes the canonical
contact for admission, token issuance, and policy changes.