Mesh.edwinmatos.rocks
Sites
← Architecture

ADR — Multi-Master Remote Administration

The three-master PKC design: every node carries all master public keys except its own, so no single lost device strands the fleet.

Adopted · 12 SEP 2026·updated September 12, 2026

Note on COM ports: The COM## numbers in this guide are the author’s own, shown as examples — your port will differ. On Windows, open Device Manager → Ports (COM & LPT) with the node plugged in to find the COM number your device enumerated as, and use that in place of the example in every command. On macOS/Linux the equivalent is a /dev/tty.*, /dev/ttyUSB*, or /dev/ttyACM* path. Always confirm your own port before running these commands.

Context

Meshtastic supports PKC (public-key) remote administration: a node can be configured and managed over the mesh (RF, BLE, or network) by another node, without a shared admin channel, if it carries the public key of the administering node in its security.admin_key list.

We want to manage the whole fleet remotely — change roles, positions, channels, and settings — without physically cabling each node every time, and without depending on a single device that, if lost or dead, would strand the fleet.

Meshtastic allows up to three admin keys per node.

Decision

We designate three “master” nodes, identified by their public keys. Every node in the fleet carries the master public keys so any master can administer it.

The three masters:

Master Node (model) Role in fleet Public key
M1 KYKM (ThinkNode M1) Everyday personal handheld base64:hytoF5RjxNLoFVmWDPu43kr185CKiwivBKfnuguf/Fs=
M2 KYKB (ThinkNode M2) Home base / gateway base64:7CDjTOmJVFaNrf+KNd1+eYZYQ7mIjMN43xtwDx8N3nY=
M5 KYKN (ThinkNode M5) Portable office/travel node base64:4VyAwe95ytDwLrWEUYaQDNeLbGg7QEOX5oO/g1NyqGg=

The rule: every node carries all three master public keys — except its own.

A node never needs its own admin key (it doesn’t remote-administer itself), so it uses that freed slot for nothing. This means:

Node type Admin keys it holds
A master node the other two master keys
Any non-master node all three master keys

This fits the 3-key slot limit exactly:

  • Masters hold 2 keys (the two that aren’t themselves).
  • Non-masters hold 3 keys (all masters).

Per-node matrix (current fleet):

Node Model Type Holds M1 Holds M2 Holds M5
KYKM (M1) ThinkNode M1 master (handheld) — ✓ ✓
KYKB (M2) ThinkNode M2 master (base) ✓ — ✓
KYKN (M5) ThinkNode M5 master (travel) ✓ ✓ —
KYKT SenseCAP T1000-E non-master (tracker) ✓ ✓ ✓
KYKR SenseCAP Solar Node non-master (router) ✓ ✓ ✓
Any future node — non-master ✓ ✓ ✓

Why this is safe to publish

The keys above are public keys. Publishing a master’s public key lets that master be trusted by a node — it does not grant anyone administrative power. Only the matching private key, which never leaves the master device, can actually issue admin commands.

So a member who wants their own node to be manageable by the net’s admins can simply add these three public keys to their node. Nothing is exposed by listing them here.

Private keys are never published, never stored in documentation, and should never be read out over a network connection (see Consequences).

How to apply the keys to a node

Add the appropriate master public keys to the node’s security.admin_key list. Prefer a serial (USB) connection — see Consequences for why network writes are unreliable for this field.

Set keys one at a time (batching this list field has produced corruption):

meshtastic --port <PORT> --set security.admin_key "base64:hytoF5RjxNLoFVmWDPu43kr185CKiwivBKfnuguf/Fs="

wait for the node to reboot, then the next key:

meshtastic --port <PORT> --set security.admin_key "base64:7CDjTOmJVFaNrf+KNd1+eYZYQ7mIjMN43xtwDx8N3nY="

and (for a non-master, the third):

meshtastic --port <PORT> --set security.admin_key "base64:4VyAwe95ytDwLrWEUYaQDNeLbGg7QEOX5oO/g1NyqGg="

Verify:

meshtastic --port <PORT> --get security

The admin_key list should contain exactly the intended keys — no empty base64: entries, and not the node’s own key.

If the list is wrong (has empty slots or the wrong keys), clear it first, then re-add:

meshtastic --port <PORT> --set security.admin_key 0

--set security.admin_key 0 clears the entire list. (Do not use "" to clear — an empty string appends a blank element and makes it worse.) After clearing, add the keys one at a time as above.

iOS app method (Meshtastic app)

Use this if you can’t cable the node. The app writes the whole key list at once, so it avoids the one-at-a-time requirement — but re-verify over serial when you next can.

  1. Connect to the node over Bluetooth.
  2. Settings → Radio Configuration → Security.
  3. Under Admin Keys, there are up to three key fields. Paste the master public key(s) this node should hold — the base64 string only. Fill:
    • a master node: the other two masters’ keys
    • a non-master node: all three masters’ keys
    • leave any unused field blank (don’t put a space or placeholder in it — empty fields must be genuinely empty).
  4. Save. The node reboots.
  5. When you’re next on a cable, confirm with meshtastic --port <PORT> --get security — the admin_key list should show exactly the intended keys and no empty entries.

You can paste each master’s public key from the tables above. These are public keys, so it’s fine to type or scan them anywhere. Do not enter any private key here.

New-node onboarding

Every new node gets the master keys as a standing first step:

  • A normal (non-master) node → add all three: M1, M2, M5.
  • If the new node is itself a master → add only the other two masters, and distribute its own new public key to every other node.

Consequences

Positive

  • Any of the three masters can administer any node — resilient to one master being lost, dead, or out of range.
  • No shared admin channel required; administration is per-key and revocable by removing a key.
  • Public keys are publishable, so members can opt their own nodes into net administration by adding these keys.

Operational cautions (learned in deployment)

  • Set admin keys one key per command, over serial. Batched writes and writes over a network (--host) connection have corrupted the list — leaving one real key plus empty base64: slots that consume the remaining capacity and block further keys.
  • Some nodes do not commit config writes reliably over Wi-Fi (--host): the CLI reports success but the node never reboots and nothing persists. The same commands over the serial port commit correctly. When a write “succeeds” but a re-read shows no change, switch to serial.
  • --get security over a network connection returns the node’s private key in the clear over that network. Read security config over serial whenever possible. If a private key is ever exposed, regenerate that node’s keypair — note that if the node is a master, its public key changes and must be redistributed to every node that carries it.
  • Removing a master (compromise, retirement) means visiting every node that carries its key and clearing/rewriting the admin_key list. There is no central revocation.

Security posture

  • Private keys never leave their device and never appear in any documentation.
  • Master devices should carry a device lock (e.g. a Bluetooth PIN other than the default) since possession of a master’s private key is what confers admin power.
  • Every node retains local serial administration regardless of admin keys, so a node is never permanently locked out — a cable always recovers it.