Quick Start Guide

This guide walks you through creating your first Catalyst Networks mesh network.

Prerequisites

• A Catalyst Networks account (sign up)
• Two machines (servers, VMs, or containers) that can reach the internet
• SSH access to both machines

Required order & rate limits

Nodes must be created in a specific order:

1. A Certificate Authority must exist in the organization before any node can register (the Create Organization step below sets one up for you).
2. At least one lighthouse must exist before you can register a regular (non-lighthouse) node.

Registration is also rate limited: 5 registrations per IP per hour and 10 registrations per organization per hour. Exceeding either limit returns HTTP 429 — pace bulk or fleet onboarding accordingly.

Steps

1. Create an Organization (network range + CA in one step)

   After logging in, click Organizations → Create Organization. The creation form sets everything up at once: enter a name, a network range (e.g., 192.168.100.0/24), and a CA name for the Certificate Authority that will sign all node certificates. You can optionally tick Create lighthouse and give it a name to provision a lighthouse at the same time.

   Note

   Prefer to add a Certificate Authority separately? You can create one later at Organization → Certificates → Create CA (/organizations/<your-org-slug>/certificates/create/). A CA must exist before any node can register.

2. Create a Registration Token

   Go to Organization → Nodes → Registration Tokens → Create Token (/organizations/<your-org-slug>/nodes/registration-tokens/create/). Set an expiration and usage limit. Copy the token — you’ll need it for both machines.

3. Install the CLI on the Lighthouse

   SSH into your lighthouse machine and install cvpn-manager. Download the latest release for your platform from Catalyst Networks Downloads and follow the Installation guide.

4. Register the Lighthouse

   Run the registration command on the lighthouse. The --is-lighthouse and --public-ip flags are required for lighthouses:

   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 YOUR_LIGHTHOUSE_PUBLIC_IP \
     --mode server

   This downloads certificates, installs Nebula, and starts the tunnel service.

5. Install the CLI and Register a Host

   SSH into the second machine, install cvpn-manager the same way (see Installation), then register as a regular host:

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

6. Verify Connectivity

   From the host, ping the lighthouse using its Nebula IP (shown during registration):

   ping 192.168.100.1

Your mesh network is now live. Both nodes can communicate securely over the Nebula overlay.

Tip

Nebula is installed automatically during registration — you don’t need to install it separately.

Next Steps

• CLI Reference — full command reference
• Registering a node — detailed registration guide with all options
• Syncing configuration — update config without re-registering