> ## 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.

# Connect an executor

> Bring an Agent or Operator online against your organization

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](/docs/platform/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

<Steps>
  <Step title="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](/docs/nodes/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**.
  </Step>

  <Step title="Copy the API key">
    The **Install** step shows the API key once, under **Store this key now**. The key starts with `exc_`.

    <Warning>
      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.
    </Warning>
  </Step>

  <Step title="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](/recipes/provision-on-bare-metal) (Agent) or [Provision on Kubernetes](/recipes/provision-on-kubernetes) (Operator).

    <Note>
      The first time the executor checks in with this key, Novacula registers it.
    </Note>
  </Step>

  <Step title="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](/docs/nodes/deploy-a-node) will offer you.
  </Step>
</Steps>

## 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

* [Deploy a node](/docs/nodes/deploy-a-node) onto your new executor.
* [Roles and permissions](/docs/platform/roles-and-permissions) — invite teammates with the right access level.