Daemon Mode

In desktop mode, cvpn-manager runs as a long-lived daemon that supervises Nebula processes and exposes an IPC interface for the desktop GUI (or any client) to control network connections.

Starting the Daemon

The daemon is activated by passing --ipc-mode to the root command:

# Linux / macOS (Unix socket)
cvpn-manager --ipc-mode socket

# Windows (named pipe)
cvpn-manager --ipc-mode pipe

When registered with --mode desktop, the systemd unit starts the daemon automatically with the appropriate flags:

cvpn-manager --ipc-mode socket \
  --config-root /etc/catalyst-networks \
  --state-db-path /var/lib/tech.deltaops.cvpn/state.db \
  --autostart

The --autostart flag tells the daemon to start all previously configured teams on boot.

IPC Protocol

The daemon listens on a Unix socket (Linux/macOS) or named pipe (Windows) and accepts newline-delimited JSON commands.

Default socket path: /var/run/tech.deltaops.cvpn/cmd.sock Default pipe name: \\.\pipe\tech.deltaops.cvpn.cmd

Request Format

{
  "action": "restart",
  "team": "my-org",
  "reason": "configuration updated",
  "request_ts": 1714992000
}

Response Format

{
  "ok": true,
  "message": "team restarted",
  "team": "my-org",
  "pid": 12345
}

Supported Actions

Action	Team Required	Description
teams	No	List all known team names
list	No	List teams with status details
status	Optional	Get status of a specific team, or all teams if omitted
start	Yes	Start a team’s Nebula process
stop	Yes	Stop a team’s Nebula process
restart	Yes	Stop and restart a team’s Nebula process
switch	Yes	Switch the active team
delete	Yes	Remove a team from the daemon
provision	No	Provision a new team from config files on disk

Examples with socat

# List all teams
echo '{"action":"teams"}' | socat - UNIX-CONNECT:/var/run/tech.deltaops.cvpn/cmd.sock

# Get status of a specific team
echo '{"action":"status","team":"my-org"}' | socat - UNIX-CONNECT:/var/run/tech.deltaops.cvpn/cmd.sock

# Restart a team's Nebula tunnel
echo '{"action":"restart","team":"my-org"}' | socat - UNIX-CONNECT:/var/run/tech.deltaops.cvpn/cmd.sock

# Stop a team
echo '{"action":"stop","team":"my-org"}' | socat - UNIX-CONNECT:/var/run/tech.deltaops.cvpn/cmd.sock

Team Name Validation

Team names (organization slugs) must match: ^[A-Za-z0-9](?:[A-Za-z0-9_-]{0,62}[A-Za-z0-9])?$

• 1–64 characters
• Starts and ends with alphanumeric
• May contain hyphens and underscores in the middle

Rate Limiting

The daemon enforces a rate limit of 30 requests per minute per client UID. Exceeding this limit returns an error response. This prevents runaway clients from overwhelming the daemon.

State Database

The daemon maintains a BoltDB database tracking provisioned teams and their state:

Default path: /var/lib/tech.deltaops.cvpn/state.db

The state database records which teams are provisioned, their configuration paths, and runtime state. The --autostart flag uses this database to determine which teams to start on daemon boot.

Timeouts

Operation	Timeout
Socket/pipe connect	5 seconds
Request/response	10 seconds
Max request size	128 KB

Graceful Shutdown

When the daemon receives SIGTERM (or the service is stopped), it:

1. Stops accepting new IPC connections
2. Sends SIGTERM to all managed Nebula child processes
3. Waits up to 5 seconds for children to exit
4. Sends SIGKILL to any remaining children
5. Cleans up the socket file and exits

Server Mode vs Desktop Mode

If your node is registered in server mode, the daemon is not used. Nebula runs directly under systemd, and the auth watchdog timer handles credential verification. The daemon and IPC protocol are only relevant for desktop mode installations.

See CLI Overview — Install Modes for a comparison.

Next Steps

• Registering a node — set up desktop mode during registration
• Maintenance commands — check-auth, checkin, Nebula management