Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.novacula.io/llms.txt

Use this file to discover all available pages before exploring further.

An executor is a piece of Novacula software you install on your own infrastructure. It authenticates to the control plane with an API key, polls outbound for work assigned to it, reconciles desired-state specs into actual blockchain client processes, and reports observed status back. Everything that happens to a node — start, config edit, version upgrade, stop, delete — is mediated by an executor.

​
Two backends

BackendRuns onMaterializes a node as
AgentA Linux host (Ubuntu 22.04+, Debian 12+)A set of systemd services
OperatorA Kubernetes cluster (1.27+)A BlockchainNode CR → ConfigMap + StatefulSet
Both implement the same ChainAdapter interface, so the same node spec is meaningful under either. See Execution backends for the comparison.

​
What flows in each direction

┌────────────────────┐        outbound HTTPS         ┌─────────────────────┐
│   Control plane    │ ◄──── syncExecutor (5s) ──── │      Executor       │
│  (Novacula cloud)  │ ◄──── ObservedNodeState ──── │ (your infrastructure)│
│                    │ ────► NodeSpec (latest rev)  │                     │
│                    │ ────► AgentUpgradeSpec /     │                     │
│                    │       OperatorUpgradeSpec    │                     │
└────────────────────┘                              └─────────────────────┘
The executor is the only side that opens connections. The control plane never reaches into your network.

​
Executor identity

Each executor has a server-side row keyed by (organizationId, name). The row carries:
  • kind — agent or operator. Set on first sync, immutable after that.
  • capabilities — JSON blob declaring which chains, networks, clients, versions, and node types this executor can run. See Executor capabilities.
  • currentVersion — the executor binary version reported on every sync.
  • channel — which release channel this executor follows (stable, beta, or internal dev). Drives the available upgrades list.
  • updatedAt — refreshed on every sync. The status virtual field returns online if now() − updatedAt < HEARTBEAT_TIMEOUT_MS (30s default), otherwise offline.
If a syncExecutor call comes in for an unknown name, the row is created on the spot — that’s how new executors register themselves.

​
Lifecycle from the UI

ActionWhat it does
Connect new executorIssues an API key + shows the install command. See Connect an executor.
View executorShows status, capabilities, hosted nodes, recent events, last API-key usage.
Upgrade executorRecords a pending upgrade spec; the executor picks it up on its next sync. See Upgrade an executor.
Deactivate executorDisables the API key and orphans the row. See Deactivate an executor.

​
Compatibility window

The control plane and executor each carry a major version. Compatibility is checked on every sync:
  • In-window — executor major == CP major. Full functionality.
  • Deprecated — executor major == CP major − 1. Sync still succeeds; UI surfaces a deprecation banner. Plan an upgrade before the next CP major release.
  • Out-of-support — executor major < CP major − 1. syncExecutor continues to accept heartbeats and serve upgrade specs, but nodes queries return 409 Conflict until you upgrade.
This is enforced by compatWindowStatus() in @vos/protocol.

​
Where to start