Skip to content
Catalyst Networks

Architecture

Overview

Catalyst Networks is built on Nebula, an open-source overlay networking tool created by Slack. Nebula creates encrypted peer-to-peer tunnels between nodes using certificate-based identity.

Catalyst Networks adds a management layer on top of Nebula:

┌─────────────────────────────────────────────┐
│           Catalyst Networks Platform         │
│  ┌──────────┐  ┌──────┐  ┌───────────────┐ │
│  │ Web      │  │ API  │  │ Celery Workers │ │
│  │ Dashboard│  │      │  │ (cert renewal, │ │
│  │          │  │      │  │  monitoring)   │ │
│  └──────────┘  └──────┘  └───────────────┘ │
│            │      │              │           │
│            ▼      ▼              ▼           │
│         ┌──────────────────────────┐        │
│         │      PostgreSQL          │        │
│         │  (orgs, nodes, certs)    │        │
│         └──────────────────────────┘        │
└─────────────────────────────────────────────┘
         │                    │
    CLI Registration     Config Download
         │                    │
    ┌────▼────┐          ┌────▼────┐
    │ Node A  │◄────────►│ Node B  │
    │ (Nebula)│  Encrypted│ (Nebula)│
    └─────────┘  Tunnel   └─────────┘

Key Components

Control Plane

The central management service (Django + PostgreSQL + Redis + Celery). It handles:

  • User authentication and authorization
  • Organization and membership management
  • Certificate Authority (CA) operations
  • Node registration and configuration
  • Certificate lifecycle (generation, renewal, revocation)
  • Webhook event delivery

Nodes

Machines running the Nebula agent. Each node has:

  • A signed certificate from the organization’s CA
  • A configuration file specifying network settings
  • A Nebula IP address within the organization’s network range

Lighthouses

Special nodes that help other nodes discover each other. Every network needs at least one lighthouse with a stable public IP address. Lighthouses act as rendezvous points — once nodes find each other, they communicate directly.

CLI (cvpn-manager)

A cross-platform command-line tool that:

  • Registers nodes with the control plane
  • Downloads certificates and configuration
  • Installs Nebula automatically during registration
  • Installs and manages the system service (systemd, launchd, or Windows SCM)
  • Periodically checks in to report status
  • Optionally runs as a daemon for desktop GUI integration

Desktop App

A GUI application (Linux, macOS, Windows) that communicates with the cvpn-manager daemon over IPC to manage network connections. The daemon supervises Nebula processes and the desktop app sends commands (start, stop, restart, switch) through a Unix socket or named pipe.

Data Flow

  1. Registration: A node runs cvpn-manager register → the CLI calls the API → the control plane generates certificates and returns configuration → the CLI writes files, installs Nebula, and starts the service
  2. Runtime: Nebula runs as a system service, creating encrypted tunnels to peers
  3. Check-in: The CLI periodically reports node version and uptime to the control plane
  4. Auth verification: On server-mode nodes, a systemd timer runs cvpn-manager check-auth every 60 seconds to verify credentials are still valid — revoked nodes are stopped automatically
  5. Config sync: cvpn-manager sync-config downloads updated configuration from the control plane and restarts Nebula
  6. Renewal: Celery workers automatically renew certificates approaching expiration