Network Authority Commands¶
Commands that create, run and administer a Network Authority.
Commands are stable unless marked Beta; Public Contract lists the level of every command. A beta command may change in a minor release.
Setup¶
genesis-mesh init¶
Creates local demo keys, an unsigned genesis file, a signed genesis file, and a CLI config file.
genesis-mesh init
Useful options:
Option |
Description |
|---|---|
|
Config path to write. Defaults to |
|
Directory for generated local artifacts. Defaults to |
|
Network name embedded in genesis. |
|
Network version embedded in genesis. |
|
Network Authority endpoint written to config. |
|
Signed genesis output path. Useful for |
|
Network Authority private key output path. |
|
Operator private key output path. |
|
Operator public key output path. |
|
Network Authority SQLite DB path to store in config. |
|
Network Authority bind host to store in config. |
|
Network Authority bind port to store in config. |
|
Optional peer bootstrap anchor in |
|
Also write Network Authority settings for |
|
Replace an existing config and generated local artifacts. Refuses to delete the directory the command is running from. |
init is suitable for local development and demos. Production key generation
should happen through an explicit key-management ceremony.
For a named sovereign on a VM, keep the paths explicit:
genesis-mesh init \
--network-name USG-NB \
--na-endpoint https://na.example.org \
--genesis-file /etc/genesis/genesis.signed.json \
--na-private-key-file /etc/genesis-mesh/keys/na.key \
--operator-private-key-file /etc/genesis-mesh/keys/operator.key \
--operator-public-key-file /etc/genesis-mesh/operator.pub \
--db-path /var/lib/genesis-mesh/na.db \
--na-host 0.0.0.0 \
--na-port 8443 \
--force
genesis-mesh na start¶
Starts a local Network Authority from config or, with --env-file, from a
settings file.
genesis-mesh na start
Useful options:
Option |
Description |
|---|---|
|
Config path to read. |
|
Override configured bind host. |
|
Override configured bind port. |
|
Override SQLite database path. |
|
|
|
Run with the production settings in this file instead of the config (v1.1.0). See below. |
From config, the NA has one operator key (privileged tier) and the default
settings. With --env-file, it is the production app (the one Gunicorn
serves) with the settings in the file: boundary policy enforcement, several
operator keys with their tiers, rate limits and every other variable in
Configuration Reference. The NA’s settings come only from the file, not from the
process environment (see Configuration Reference for what is still read from
it).
--config, --db-path and --evidence-store are refused with --env-file.
The port is PORT from the file (default 8443), the host 127.0.0.1;
--host and --port override them. The command prints the settings that
matter for development, without key material:
genesis-mesh na start --env-file local/na.env
This command uses Werkzeug’s development server. Use the container entry point and Gunicorn for production-style deployments.
If genesis-mesh dev down was run earlier, recreate local config first with
genesis-mesh init; dev down removes genesis-mesh.toml, .genesis-mesh/,
and local .node*/ smoke-test directories.
genesis-mesh keygen operator¶
v1.1.0 — Local Governed Network Authority
Generates an operator (admin) key pair and, with --env-file, registers its
public key and tier in a Network Authority settings file
(OPERATOR_PUBLIC_KEYS_JSON and OPERATOR_KEY_TIERS_JSON), keeping every
other line. The tier defaults to standard: what a controller needs for
/admin/boundary/evaluate and reads, without publishing policies, issuing
attestations or registering keys. The command refuses existing key files, and
a key ID already registered with another public key unless --replace is
given. Restart the NA to load a new key.
To rotate a key, remove its two files and run the command again with
--replace, then restart the NA.
genesis-mesh keygen operator \
--output local/.genesis-mesh/keys/controller \
--key-id controller \
--tier standard \
--env-file local/na.env
Exit code 0 on success; 1 on failure.
Admin¶
genesis-mesh admin invite¶
Creates a single-use invite token through the operator-authenticated admin API.
genesis-mesh admin invite --role anchor
The command prints only the token ID, so shells can capture it:
INVITE_TOKEN=$(genesis-mesh admin invite --role anchor)
Useful options:
Option |
Description |
|---|---|
|
Config path to read. |
|
Network Authority endpoint override. |
|
Operator private key path. Can be used instead of a config file. |
|
Operator key ID. Defaults to |
|
Role to assign. Can be repeated. |
|
Maximum certificate validity allowed by the invite. |
|
Invite token lifetime (the NA’s default: 24 hours, one hour for an edge invite). |
|
Bind the invite to one node public key. |
|
Beta (v1.7.0): make an edge invite for the edge node with this sovereign ID. Needs |
|
Beta (v1.7.0): the resource prefix of the edge node’s executor key, such as |
An edge invite is redeemed by the edge agent (genesis-mesh-edge enroll),
which registers its executor key at /join. Bind it to the device with
--recipient-key and the node key genesis-mesh-edge init prints; see
The Edge Agent.
genesis-mesh admin edge-nodes¶
Beta (v1.7.0). Lists edge nodes, newest enrolment first, as JSON
(GET /admin/edge-nodes, read tier).
genesis-mesh admin edge-nodes --status offline --limit 50
Option |
Description |
|---|---|
|
|
|
Edge nodes per page, 1 to 500 (default 100). |
|
The |
genesis-mesh admin revoke¶
Revokes a certificate through the operator-authenticated admin API.
genesis-mesh admin revoke <cert-id> --reason key_compromise
Useful reasons are key_compromise, cessation_of_operation, superseded,
and unspecified. For an edge node (v1.7.0) it revokes every certificate the
node holds, retires its executor key and revokes the grants that key bears;
the printed JSON has an edge_node block.
genesis-mesh admin revoke-operator-key¶
Switches an operator key off immediately, without restarting the Network Authority. Use this when an operator key is lost or stolen.
genesis-mesh admin revoke-operator-key operator-alice --reason key_compromise
This is a privileged-tier operation: a standard operator key receives
403 insufficient_operator_tier.
The key stops authenticating on the next request — no restart, no config edit. Rejection happens before the signature is checked and before the nonce is consumed, so a revoked key cannot act at all, including revoking other operators.
Warning
Revocation is terminal for the life of the deployment. There is no
un-revoke endpoint, and the revocation is stored in the NA’s database: the key
ID stays revoked across restarts and configuration edits, even with a new
public key. To replace the key, generate a new key under a new key ID
(genesis-mesh keygen operator --env-file ...) and restart the NA.
The service refuses to revoke the last usable operator key
(409 last_active_operator_key) — otherwise this command could cause exactly
the outage it exists to avoid. Configure a second operator key first.
A caller presenting a revoked key is told only Unknown admin key, identical to
an unrecognised key: whoever holds a stolen key learns nothing about whether the
compromise was noticed. The real reason is recorded in the audit log as
admin_auth_failed with reason: revoked_key, alongside the
operator_key_revoked event.
Database¶
genesis-mesh na migrate-db¶
v0.60: High Availability
Copy a Network Authority SQLite database into an empty PostgreSQL database and
verify it. Stop the NA first. The source is opened read-only and left
untouched; --from takes a path or sqlite:///path. The target must be
empty, and the source must be at the current schema version (start this
release on it once).
genesis-mesh na migrate-db \
--from sqlite:///var/lib/genesis-mesh/na.db \
--to "$DATABASE_URL" \
--genesis genesis.signed.json \
--report migration.json
Every table’s row count and content digest must match the source, and the
target must pass na verify-db; otherwise the command exits non-zero. A
database_migrated audit event is written to the target. See
High Availability.
genesis-mesh na verify-db¶
v0.60: High Availability
Verify a Network Authority database (SQLite or PostgreSQL) after a restore or
migration. It checks that boundary policies match their stored digests, that
CRL sequences have no gaps with only the highest one active, and that the
evidence store is an unbroken hash chain. With --genesis it also checks
every evidence signature, each NA signature with the key valid at the
entry’s time: the NA key history in the database is verified from the
genesis block’s root key, never taken from its rows alone (v1.5.0).
genesis-mesh na verify-db --database-url "$DATABASE_URL" --genesis genesis.signed.json
genesis-mesh na verify-db --db-path /var/lib/genesis-mesh/na.db
Prints a JSON report; exit code 0 when every check passes, 1 otherwise.
Managed Operations¶
genesis-mesh managed backup¶
Beta.
Creates a consistent online backup of a Network Authority SQLite database.
For PostgreSQL, use pg_dump.
genesis-mesh managed backup \
--db-path /var/lib/genesis-mesh/na.db \
--output /backups/genesis-mesh-na-YYYYMMDDHHMMSS.db
genesis-mesh managed restore¶
Beta.
Restores a Network Authority database from a backup. Stop the Network Authority before running it.
genesis-mesh managed restore \
--db-path /var/lib/genesis-mesh/na.db \
--backup /backups/genesis-mesh-na-known-good.db \
--pre-restore-backup /backups/na-before-restore.db \
--yes
The command validates that the backup looks like a Genesis Mesh NA database and
requires --yes before replacing the DB file.
genesis-mesh managed audit-export¶
Beta.
Exports redacted Network Authority audit events as JSON Lines or JSON, from a SQLite database. The audit log is plain rows in the NA database, not signed or chained; for records whose changes are detectable, use the evidence store (Evidence and Audit Commands).
genesis-mesh managed audit-export \
--db-path /var/lib/genesis-mesh/na.db \
--output /var/log/genesis-mesh/audit-events.jsonl
Use --event-type recognition_treaty_issued to export one event class and
--format json when a JSON array is easier to ingest.
Key and Genesis Commands¶
These are the stable commands of a key ceremony: generate the root and NA
keys, write the genesis block, and sign it with the root key on an offline
machine. genesis-mesh init does all of this in one step for local use and
writes every key, the root key included, to one directory. For a sovereign
that other parties rely on, follow the root key ceremony in
Key Succession and the Root Key.
genesis-mesh keygen root, keygen network-authority and keygen node¶
Write an Ed25519 key pair: the private key to <output>.key and the public
key to <output>.pub.
genesis-mesh keygen root --output keys/root --key-id rs-2025-q1
genesis-mesh keygen network-authority --output keys/na --key-id na-2025-q1
genesis-mesh keygen node --output keys/node --key-id node-1
Option |
Description |
|---|---|
|
Output path without extension (required). |
|
Key identifier. Defaults to |
genesis-mesh genesis create¶
Write an unsigned genesis block.
genesis-mesh genesis create \
--network-name "USG" \
--network-version "v0.1" \
--root-key keys/root.pub \
--na-key keys/na.pub \
--output genesis.json
Option |
Description |
|---|---|
|
Network name (required). |
|
Network version (default |
|
Path to the root public key (required). |
|
Path to the NA public key (required). |
|
The NA key’s |
|
Bootstrap peer anchor in |
|
Output path (required). |
genesis-mesh genesis sign¶
Sign a genesis block with the root private key. Run it on the offline machine that holds the root key.
genesis-mesh genesis sign \
--genesis genesis.json \
--root-private-key keys/root.key \
--key-id rs-2025-q1 \
--output genesis.signed.json
Option |
Description |
|---|---|
|
Unsigned genesis block (required). |
|
Root private key (required). |
|
Root key identifier (default |
|
Signed genesis block path (required). |
genesis-mesh genesis verify and genesis-mesh info¶
genesis verify checks the genesis block’s signatures against the root public
key the block itself names, and exits 1 when one fails. It does not tell you
whether that root key is the one you expect: compare root_public_key with a
copy you obtained out of band. info (beta) prints the block’s network, keys,
validity and allowed suites.
genesis-mesh genesis verify --genesis genesis.signed.json
genesis-mesh info --genesis genesis.signed.json