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.

After deploy, the node detail page’s Configuration tab shows the active spec and an Edit configuration action that opens a deploy-wizard-style dialog pre-filled with the current values. Submitting writes a new spec to the control plane; the executor picks it up on its next poll.

​
What you can edit today

FieldEditableNote
Chain, network, node typeNoPick at deploy; never changes for a given node.
Client choice (e.g. geth vs reth)NoSwitching client = redeploy.
Client versionNot in-UI yetSee Upgrade a node — currently requires delete + redeploy.
Config-file overridesYesPer-process file (bitcoin.conf, fullnode.yaml, config.conf, …). Validated against the chain adapter’s whitelist.
CLI argument overridesYesPer-process flag list. Validated against the chain adapter’s managed-flag set.
checkpoint-sync-url (Ethereum CL)YesFirst-class field on Ethereum CL clients; fast-syncs from a trusted checkpoint.
CPU / RAM / disk requests + limitsRoadmapResource changes need executor-side headroom checks before they can be applied at runtime; deferred. Until they land, resources stay fixed at deploy values — re-deploy if they need to change.
Storage class (Operator only)NoBound at PVC creation.

​
How edits flow

  1. You submit the form. The dialog computes the diff between the current spec and your inputs and surfaces an “N changed” badge so you can see the size of the change at a glance.
  2. The control plane validates against the executor’s capabilities and the chain adapter’s configOverrideSchema.
  3. Node.spec is updated in place — there is no spec-revision counter, no Revisions sub-tab, and no Rollback action today (see Roadmap).
  4. The executor sees the new spec on its next poll.
  5. Reconciler diffs and applies — regenerates the config file, restarts the affected process so it re-reads.
  6. node.lifecycle.transition events are written as processes go through stopping → starting → running again.

​
Override validation

Every chain adapter ships a configOverrideSchema describing two override surfaces:
  • files — for chains where config lives in a config file (Bitcoin, Sui, Tron, Monad). The schema lists managedPaths (keys the platform owns — data-dir, RPC bindings, ports — rejected if you try to override) and knownKeys (commonly-tuned keys with type hints + descriptions, rendered with helpful UI).
  • args — for chains where config is CLI flags (Ethereum, BSC, Igra, Ink). The schema lists managedFlags per role (rejected if overridden) and knownFlags per role (typed + described).
Submitting a managed key or flag returns invalid_node_config with the offending entries enumerated.
Anything not on the managed list and not on the known list is still accepted as a free-form override — the platform passes it through. The known-keys / known-flags list is for UX, not gating.

​
Capacity warnings

If your edit would push CPU, RAM, or disk below the per-network defaults from the chain adapter, the form surfaces a non-blocking warning. Submission still succeeds; you’ll see warnings on the node detail page until you raise the requests, and the node may show reconciliation churn or stalled sync if the budget really is too tight.

​
What edits don’t do

  • They don’t trigger a re-sync from genesis. The data directory is preserved across restarts.
  • They don’t move the node to a different executor. That requires delete + redeploy.
  • They don’t change the node’s identity. The name and id stay the same; only the spec evolves.
  • They don’t produce a versioned history you can roll back to. Audit records that the spec changed; the field-level diff lives only in the dialog’s preview at edit time.

​
Roadmap

Three items that are explicit gaps today:
  • Spec versioning — a specRevision counter on Node plus an immutable history table, so prior specs can be inspected after the fact.
  • Configuration → Revisions sub-tab — list every revision with timestamp, author, change summary.
  • Rollback — a forward write that re-applies a historical spec, audit-friendly (rollback is a new revision, not a delete).
These ship together; until then, the live edit dialog and cpNode.updateNode mutation are the only path. The wider Upgrade a node flow shares the same pendingUpgrade infrastructure as executor upgrades and is also roadmap.

​
Permissions

owner and admin. Members see the form but can’t submit. See Roles and permissions.