FAQ

General

What is the difference between Catalyst Networks and Tailscale?

Catalyst Networks is built on Nebula (certificate-based identity), while Tailscale uses WireGuard (key-based). Key differences:

Self-hostable control plane — Catalyst Networks can be fully self-hosted
Certificate-based identity — Better for enterprise PKI integration
Multi-tenant by design — Built for MSPs and teams managing multiple networks

Can I self-host Catalyst Networks?

Yes. The entire platform can be deployed on your own infrastructure using Docker Compose. Kubernetes deployment is possible but not officially packaged yet.

What ports does Nebula need?

Nebula uses a single UDP port (default 4242). This port must be open on lighthouse nodes. Regular nodes behind NAT typically don’t need port forwarding.

CLI

Do I need to install Nebula separately?

No. The CLI (cvpn-manager) automatically downloads and installs the correct Nebula binary for your platform during cvpn-manager register. You can also manage Nebula manually with cvpn-manager nebula install and cvpn-manager nebula update.

What is the difference between server mode and desktop mode?

On Linux, --mode server creates a systemd unit that runs Nebula directly plus an auth watchdog timer. --mode desktop creates a unit that runs cvpn-manager as a daemon, supervising Nebula and exposing an IPC socket for the desktop GUI. Use server mode for headless infrastructure and desktop mode for workstations. See Install Modes.

What can the node API token access?

The token returned during registration is scoped to two endpoints: /checkin/ (heartbeat) and /download_config/ (config download). All other API endpoints return 403 and require a user/admin JWT. See Node API Token Scope.

Nodes

My node won’t connect — what should I check?

Verify the lighthouse is reachable from the node’s network
Check that UDP port 4242 (or your configured port) is open on the lighthouse
Verify the node’s certificate hasn’t expired: check the dashboard or run nebula-cert print -path /etc/catalyst-networks/{org}/node.crt
Check Nebula logs: journalctl -u catalyst-networks-{org} (server mode) or journalctl -u catalyst-networks-{org} (desktop mode — look for the daemon logs)
Verify credentials are valid: cvpn-manager check-auth --org-slug {org}

My node says “auth revoked” — what happened?

The control plane rejected the node’s API token (401/403/404). The check-auth command detected this, stopped the Nebula service, and wrote auth-revoked.json to prevent further attempts. To resolve:

Check the dashboard — the node may have been deleted or its token regenerated
Delete the breadcrumb file: rm /etc/catalyst-networks/{org}/auth-revoked.json
If the node was removed, delete the org directory and re-register

How do I add a node behind NAT?

Nodes behind NAT work automatically. Nebula uses UDP hole-punching to establish direct connections. The lighthouse acts as a rendezvous point to facilitate this.

Certificates

How do I renew an expired certificate?

If auto-renewal is enabled (default), certificates renew automatically 14 days before expiration. To manually renew:

Dashboard: Go to Nodes → select the node → click “Renew Certificate”
API: POST /api/org/{slug}/nodes/{id}/renew_cert/
CLI: cvpn-manager sync-config --overwrite-certs

What happens when a certificate expires?

The node loses connectivity to the mesh network. Other nodes will reject connections from the expired certificate. Renew the certificate and restart Nebula to restore connectivity.

Billing

Is there a free option?

Yes. Catalyst Networks Community Edition is free, open source, and self-hosted on infrastructure you control. It runs a single organization with no hard node cap, and includes certificate authority management, node registration, and security groups. Managed hosting plans (with backups, updates, and support expectations) are available separately.

Can I upgrade or downgrade my plan?

Yes, you can change plans at any time from the billing page. Changes take effect immediately.