Skip to content
Ployz

ployzctl mesh — manage the network

The mesh command manages the WireGuard overlay network that connects cluster machines. Each mesh network gives machines a flat, encrypted overlay with stable IP addresses independent of the underlying physical network. Ployz owns the mesh end-to-end, which is what makes single-command primitives like machine add and migrate possible.

Terminal window
ployzctl mesh <subcommand> [flags]
ployzctl network <subcommand> [flags]  # alias

Subcommands

Section titled “Subcommands”

list — list mesh networks

Section titled “list — list mesh networks”

List all mesh networks known to the daemon, including their names and current state.

Terminal window
ployzctl mesh list

The response includes each network’s name and state string. Use --json to get the full structured payload.

Terminal window
ployzctl --json mesh list

status — show status of a network

Section titled “status — show status of a network”

Show the detailed status of a named mesh network, including the local machine’s overlay IP and lifecycle state.

Terminal window
ployzctl mesh status <network>

  • network (string) required:

    Name of the mesh network to inspect.

The response includes the network name, the local machine’s overlay IP, and the lifecycle string.

join — join a mesh network

Section titled “join — join a mesh network”

Join the local machine to an existing mesh network using a join token. The token can be passed directly or provided on stdin.

Terminal window
ployzctl mesh join [--token <token>] [--token-stdin]

  • --token (string):

    The join token string. Obtain this from the coordinator machine or from a cluster invite.

  • --token-stdin (boolean):

    Read the join token from stdin instead of the --token flag. Useful in pipelines where the token should not appear in the process list.

ready — check if the mesh is ready

Section titled “ready — check if the mesh is ready”

Check whether the mesh is ready to accept workloads. Reports readiness, the current phase, store health, sync connectivity, and whether the workload subnet is present.

Terminal window
ployzctl mesh ready [--json]

  • --json (boolean):

    Print the full readiness payload as JSON. Note: this is a subcommand-level --json flag in addition to the global one.

This command exits with code 0 if the mesh is ready and a non-zero code if it is not, making it suitable for use in readiness probes and startup scripts.

Terminal window
ployzctl mesh ready && echo "mesh is up"

create — create a new mesh network

Section titled “create — create a new mesh network”

Create a new named mesh network. The network is initialized on the local machine and ready for other machines to join.

Terminal window
ployzctl mesh create <network>

  • network (string) required:

    Name for the new mesh network.

init — initialize a new mesh

Section titled “init — initialize a new mesh”

Initialize a mesh network, optionally reading the network name from stdin. This is the lower-level initialization primitive used when the network name is generated or piped from another command.

Terminal window
ployzctl mesh init [<network>] [--name-stdin]

  • network (string):

    Name of the mesh network to initialize. Optional if --name-stdin is set.

  • --name-stdin (boolean):

    Read the network name from stdin. Cannot be combined with a positional network argument.

start — start a mesh network

Section titled “start — start a mesh network”

Start a previously created or stopped mesh network.

Terminal window
ployzctl mesh start <network>

  • network (string) required:

    Name of the mesh network to start.

stop — stop a mesh network

Section titled “stop — stop a mesh network”

Stop the running mesh network. WireGuard interfaces are brought down and peer connectivity is severed.

Terminal window
ployzctl mesh stop [--force]

  • --force (boolean):

    Force-stop the mesh even if workloads are still running. Without --force, the daemon may refuse to stop if active services depend on the overlay network.

destroy — destroy a mesh network

Section titled “destroy — destroy a mesh network”

Permanently destroy a mesh network, removing all associated configuration and state. This is irreversible.

Terminal window
ployzctl mesh destroy [<network>] [--name-stdin]

  • network (string):

    Name of the mesh network to destroy. Optional if --name-stdin is set.

  • --name-stdin (boolean):

    Read the network name from stdin.

self-record — print this machine’s mesh record

Section titled “self-record — print this machine’s mesh record”

Print the local machine’s mesh membership record. This includes the machine’s overlay IP, public key, endpoints, and region role. Useful for debugging connectivity and for sharing the record with other machines during manual cluster setup.

Terminal window
ployzctl mesh self-record

Use --json to get the full structured MachineMembership record.

Terminal window
ployzctl --json mesh self-record

Examples

Section titled “Examples”
Terminal window
# Create a new mesh network named 'prod'
ployzctl mesh create prod


# Check mesh readiness (exits 0 if ready)
ployzctl mesh ready


# Show the status of the 'prod' network
ployzctl mesh status prod


# List all networks
ployzctl mesh list


# Join a network using a token
ployzctl mesh join --token eyJ...


# Join using a token from stdin (avoids token in process list)
echo "$MESH_TOKEN" | ployzctl mesh join --token-stdin


# Print this machine's mesh record
ployzctl --json mesh self-record


# Stop the mesh (requires no active workloads)
ployzctl mesh stop


# Destroy the mesh network permanently
ployzctl mesh destroy prod


# Use the network alias
ployzctl network list