Skip to main content
An executor is the Novacula software you install on your own infrastructure: an Agent on a bare-metal host or VM (it runs nodes as systemd services), or an Operator in a Kubernetes cluster (it runs nodes as pods). One executor per install. The executor only ever connects out to Novacula — no inbound ports to open. Connecting one is a single flow in the UI: you name the executor, copy the API key it shows you, and run one install command on your host or cluster.

​
Prerequisites

  • The owner or admin role — you need it to create the API key. See Roles and permissions.
  • One of:
    • A Linux x86_64 host with sudo, for the Agent.
    • A Kubernetes cluster (1.27+ recommended) where you can run helm, for the Operator.
  • Outbound HTTPS from that host or cluster to the Hub URL.

​
Steps

1

Open Connect Executor

In the sidebar, open Executors, then click Connect Executor.On the Configure key step, choose a kind:
  • Agent — for bare metal, VMs, and lightweight hosts.
  • Operator — for Kubernetes.
Enter a Label — this is the name you’ll see in the executors list and pick as a target when you deploy a node. It’s unique within your organization.Optionally set Expires at for the API key. Leave it blank to use the default one-year lifetime. Click Continue.
2

Copy the API key

The Install step shows the API key once, under Store this key now. The key starts with exc_.
The full key is shown only on this screen. Copy it now into a password manager or secrets vault — you cannot read it again. If you lose it, connect a new executor to get a fresh key.
3

Run the install command

The same screen gives you a copy-pasteable command with the key already filled in. Copy the exact command shown on the Install step and run it on your host or cluster.For the full walkthrough, follow the recipe for your backend: Provision on bare-metal (Agent) or Provision on Kubernetes (Operator).
The first time the executor checks in with this key, Novacula registers it.
4

Confirm it's online

Back in Executors, the new row flips to online once the executor checks in (a few seconds). Its supported chains, networks, clients, and versions populate at the same time — that’s what the deploy node wizard will offer you.

​
Troubleshooting

If the row stays offline (Novacula marks an executor offline about 30 seconds after it stops checking in):
  • Check the executor’s logs — see the recipe for your backend type.
  • Confirm outbound HTTPS from the host or cluster to the Hub URL.
  • Re-check the API key — make sure it was copied whole, with no trailing whitespace. If you suspect the key, connect a new executor to issue a fresh one.

​
Next steps