Registering a Node

The register command connects a machine to your Catalyst Networks mesh by calling the control plane API, downloading certificates and configuration, installing Nebula, and setting up system services.

Authentication

Registration supports two mutually exclusive authentication methods:

Registration Token

Tokens are created in the web dashboard under your organization’s settings. They can be scoped with an expiration date and usage limit.

cvpn-manager register \
  --api-base https://app.catalystnetworks.io \
  --org-slug my-org \
  --node-name web-server-1 \
  --registration-token YOUR_TOKEN \
  --mode server

User JWT

Authenticate with your user account’s JWT. Useful for automation or when you don’t want to create a registration token.

cvpn-manager register \
  --api-base https://app.catalystnetworks.io \
  --org-slug my-org \
  --node-name web-server-1 \
  --access-token YOUR_JWT \
  --mode server

Lighthouse vs Host

Every network needs at least one lighthouse — a node with a stable public IP that helps other nodes discover each other. All other nodes are regular hosts.

Register a Lighthouse

cvpn-manager register \
  --api-base https://app.catalystnetworks.io \
  --org-slug my-org \
  --node-name lighthouse-1 \
  --registration-token YOUR_TOKEN \
  --is-lighthouse \
  --public-ip 203.0.113.10 \
  --mode server

Note

Lighthouses must have --is-lighthouse and --public-ip set. The public IP is embedded in the Nebula configuration so other nodes know how to reach the lighthouse.

Register a Host

cvpn-manager register \
  --api-base https://app.catalystnetworks.io \
  --org-slug my-org \
  --node-name app-server-1 \
  --registration-token YOUR_TOKEN \
  --mode server

Hosts behind NAT work automatically — Nebula uses UDP hole-punching via the lighthouse for peer discovery.

Install Modes (Linux)

The --mode flag controls how Nebula is managed after registration:

Server Mode

Use for: headless servers, VMs, always-on infrastructure.

cvpn-manager register ... --mode server

Creates two sets of systemd units:

1. catalyst-networks-{org}.service — runs nebula -config /etc/catalyst-networks/{org}/config.yml directly under systemd. Restarts on failure with a 5-second delay.

2. catalyst-networks-auth.service + catalyst-networks-auth.timer — runs cvpn-manager check-auth --all every 60 seconds (and 30 seconds after boot) to verify credentials are still valid. If the control plane revokes a node’s token, the auth watchdog stops the Nebula service and writes a breadcrumb file.

Desktop Mode

Use for: workstations and laptops with the Catalyst Networks desktop app.

cvpn-manager register ... --mode desktop

Creates a single systemd unit that runs cvpn-manager as a daemon. The daemon supervises Nebula as a child process and exposes an IPC socket for the desktop GUI to send commands (start, stop, restart, switch networks).

No auth timer is created — the desktop app manages auth checks directly.

See Daemon Mode for details on the IPC protocol.

Tip

If --mode is not specified, it defaults to desktop. For unattended servers, always pass --mode server.

On macOS, registration creates a launchd plist instead of a systemd unit. On Windows, the service is managed through the Windows Service Control Manager.

All Flags

Flag	Env Variable	Description
--api-base	CATALYST_API_BASE	Control plane API URL (required)
--org-slug	CATALYST_ORG_SLUG	Organization slug (required)
--node-name	CATALYST_NODE_NAME	Name for this node (required)
--registration-token	CATALYST_REGISTRATION_TOKEN	Registration token (token auth flow)
--access-token	CATALYST_ACCESS_TOKEN	User JWT (JWT auth flow)
--is-lighthouse	CATALYST_IS_LIGHTHOUSE	Mark this node as a lighthouse
--public-ip	CATALYST_PUBLIC_IP	Public IP address (required for lighthouses)
--fqdn	CATALYST_FQDN	Fully qualified domain name
--external-port	CATALYST_EXTERNAL_PORT	UDP port for Nebula (auto-detected if omitted)
--mode	CATALYST_INSTALL_MODE	Install mode: server or desktop (Linux only)

All flags can also be set via environment variables.

What Happens During Registration

1. Port selection — If --external-port is not set, the CLI scans UDP ports 4242–4442 for the first available port.

2. API call — The CLI POSTs to /api/org/{slug}/nodes/register/ with the node details. The control plane generates certificates, assigns a Nebula IP, and returns a configuration package.

3. File creation — Certificates (ca.crt, node.crt, host.crt, node.key, host.key), configuration (config.yml), credentials (credentials.json), and metadata (node-config.json) are written to the organization directory.

4. Credential storage — The node’s API token is stored in the OS keyring (service catalyst-manager, account {org}:{node_id}). If the keyring is unavailable, the token remains in credentials.json.

5. Nebula installation — If Nebula is not already installed, the CLI downloads and installs the correct binary for the current platform and architecture.

6. Service setup — A systemd unit (Linux), launchd plist (macOS), or Windows service is created and started.

Environment Variable Registration

For automated deployments, all flags can be provided through environment variables:

export CATALYST_API_BASE=https://app.catalystnetworks.io
export CATALYST_ORG_SLUG=my-org
export CATALYST_NODE_NAME=auto-node-$(hostname)
export CATALYST_REGISTRATION_TOKEN=your-token
export CATALYST_INSTALL_MODE=server

cvpn-manager register

Re-registration

If a node is already registered (i.e. credentials.json exists), the register command will fail. To re-register:

1. Stop the Nebula service
2. Remove the organization directory (e.g. /etc/catalyst-networks/my-org/)
3. Remove the node from the dashboard
4. Run register again

Next Steps

• Sync configuration — update config without re-registering
• Maintenance commands — credential checks, heartbeats, Nebula updates