Online, Offline and Expired — Guardian

Credential States

The realm credential is your tree's link to VeilNet. It is always in one of three states:

State	What it means	What you do
Online	The credential carries a renewal address and token. The guardian renews it with VeilNet over HTTPS as it nears expiry. This is the stack's only connection beyond your network. A failed renewal is recorded, but it stops nothing.	Allow one route out, to the renewal address. Read any recorded error.
Offline	The credential carries no renewal address or token. The guardian never connects out, and the console shows renewal as offline. This is a normal state, not an error.	Note the expiry date. VeilNet hands over a fresh credential before it expires.
Expired	The credential has passed its expiry date, or its link to VeilNet has been cut. Your tree is cut off from VeilNet at that one link. Below it, the guardian keeps commissioning, issuing, renewing, revoking and blocking, and machines keep exchanging data.	Put a fresh credential in place when you have one. Nothing stops in the meantime.

Fig. 01 — Credential states

An online credential renews itself, and a failed renewal is recorded and retried. The tree is cut off only if renewal keeps failing until the credential lapses. You replace an offline credential by hand before it lapses. If either kind lapses, put a fresh credential from VeilNet in place and restart the API server. In every state, everything inside your tree keeps working.

Reading the State

The dashboard's Realm credential panel shows the time left, when the credential last renewed and how it renews. If renewal is failing or the tree is cut off, a banner appears above the dashboard and the Realms page.

Fig. 02 — The realm credential, as the dashboard shows it01 / 04

Online: the credential renews itself as it nears expiry, and the dashboard shows when it last renewed.

Dashboardguardian-adminRealm credentialtier2Renews itself with VeilNet. A failed renewal stops nothing inside this tree.23days until 31 Oct 2026Guardian IDgrd_7Q2M4KDelegation levels1 — read from the verified chainLast renewal1 Oct 23:10 · okRenews withVeilNet · the renewal address in the credentialSevered at—

Failing: the console shows and records the error. Nothing inside your tree stops.

Dashboardguardian-adminRenewal with VeilNet is failing. Nothing inside this tree has stopped.If it lapses on 20 Oct 2026, the tree is cut at that edge only. Every sub-realm and node here keeps being issued and renewed.renewal failed: dial tcp: i/o timeoutRealm credentialtier2Renews itself with VeilNet. A failed renewal stops nothing inside this tree.12days until 20 Oct 2026Guardian IDgrd_7Q2M4KDelegation levels1 — read from the verified chainLast renewal1 Oct 23:10 · failing sinceRenews withVeilNet · the renewal address in the credentialSevered at—

Offline: nothing connects out, and renewal reads as offline. This is a normal state, not an error.

Dashboardguardian-adminRealm credentialtier2Renews itself with VeilNet. A failed renewal stops nothing inside this tree.41days until 18 Nov 2026Guardian IDgrd_7Q2M4KDelegation levels1 — read from the verified chainLast renewaloffline — the credential carries no renewal pairRenews withnothing — a fresh credential is handed overSevered at—

Expired: the tree's link to VeilNet has lapsed. Everything inside the tree keeps working.

Dashboardguardian-adminThis tree's link to VeilNet has lapsed. Nothing inside it has stopped.Its delegation lapsed on 1 Oct 2026, or its link to VeilNet was severed. Every sub-realm and node here keeps being issued, renewed and blocked. A fresh credential for this realm restores the link, with nothing re-commissioned.Realm credentialtier2Renews itself with VeilNet. A failed renewal stops nothing inside this tree.7days since it lapsed on 1 Oct 2026Guardian IDgrd_7Q2M4KDelegation levels1 — read from the verified chainLast renewal1 Sep 23:10 · failing sinceRenews withVeilNet · the renewal address in the credentialSevered at1 Oct 00:00

Setup shows the same state in its credential line each time it runs. It warns if the credential has expired, but it still accepts it.

Renewal Timing

An online guardian renews its realm credential automatically, by default 14 days before it expires. GUARDIAN_RENEWAL_LEAD_DAYS sets this lead time. After each attempt, the guardian checks again on this schedule:

When	Next check
Nothing is due	Every 6 hours
A failure that may clear: a timeout, a 429 or a 5xx	After 1 minute, doubling up to 6 hours. Retry-After is honoured
The credential has just expired	After 1 minute
A refusal in the first hour after expiry	Every 5 minutes

A renewed credential takes effect at once. The guardian realm's admin node is re-signed under it, and the new link spreads to your machines from there. The other admin nodes, the sub-realms and the machines pick it up when they next renew.

Granted Powers

The realm credential decides which powers your tree can use: telemetry, and the block, compartments and networks powers that the console acts with. Check them on Settings → Realm control when the credential is first in place, and again whenever a fresh one arrives.

If the credential withholds	What happens
Telemetry	Each admin node still runs for control actions. Telemetry shows in-band as `withheld`, and the console reads the fleet only from what machines export.
Block, compartments or networks	The console refuses that action before anything is signed. Settings → Realm control shows the power as withheld by this guardian's delegation.

When a fresh credential grants a power that the old one did not, the guardian re-signs every sub-realm delegation that lacks it, with the same roots and depth. No machine is re-commissioned.

Guardian console — Settings, a power withheldIllustrative

Settingsguardian-adminSettingsHow this guardian stack is configured, read back from the API and the deployment.Read-only. The API has no settings routes — every value here is set on the host, and each one names where.Realm controlWhat operators may do to a running node, and through what.Console controlOperators block, move and route nodes here, through each realm's admin node.onGUARDIAN_CONSOLE_CONTROL · secrets/.envAdmin nodesOne per realm, made with the realm and started with this stack. Each orders its realm's telemetry, and is given a power that acts on members for one action at a time.one per realm · in the API containerone daemon eachTelemetryRead a member's own report. Held between actions, on a week-long credential renewed daily.grantedcredential · chainBlockMake a node an outsider to every member of its realm, or let it back in. Held for ten minutes at most, for one action.withheld by this guardian's delegationcredential · chainCompartmentsMove a node to other compartments while it runs. Its credential keeps the ones it was commissioned with.granted · guardian-admincredential · chainNetworks servedChange which networks a node forwards for its realm. conflux up --subnet on the machine sets them again.granted · guardian-managercredential · chainNodes themselves are issued no power. Every action is recorded, refusals included, for auditors.

Adopting a Fresh Credential

A fresh credential for the same realm, renewed or re-issued, replaces the old one when the API server restarts. For an offline deployment, VeilNet hands it over on hard media. To put it in place:

0 of 3 done

$ cp -f /media/usb/guardian_credential secrets/guardian_credential

The dashboard's Realm credential panel shows the new expiry date.
Sub-realm delegations are kept, and any delegation that lacks a power the new credential grants is signed again. Every machine stays as it was.

The guardian follows three rules when it adopts a credential:

It adopts a fresh credential only if it was issued later than the one it holds.
It refuses a credential for another realm, and the realm it already holds keeps running.
The realm's key, every sub-realm and every machine stay as they are.

After a Lapse

A lapsed realm credential revokes nothing. Every machine keeps its credential, its address and its realm, and machines in the same realm keep exchanging data.

Inside the tree, the guardian keeps commissioning, renewing, revoking and blocking. Each realm's admin node keeps issuing its commands. Every manifest and every renewal lists your own bootstrap nodes first, so a fleet cut off from VeilNet still bootstraps from them.

Nothing else in the stack needs the internet. With no outbound access at all, the guardian still runs setup, commissions machines, renews, revokes, blocks and collects telemetry. For the settings this needs, see Air-Gapped Installation.

Credential States

Reading the State

Renewal Timing

Granted Powers

Adopting a Fresh Credential

Replace the old file+

Check it with setup+

Restart the API server+

After a Lapse