Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/getployz/ployz/llms.txt

Use this file to discover all available pages before exploring further.

Machines are the compute units of a Ployz cluster. Every machine runs ployzd and participates in the WireGuard mesh, the NATS control plane, and the workload runtime. You add and remove machines with explicit commands — there is no autoscaler and no background scheduler placing machines for you.

​
Listing machines

ployzctl machine ls
This shows every machine in the cluster, including its lifecycle state, overlay IP, region role, and authority posture. Use --json for structured output suitable for scripting.

​
Initializing a new machine

machine init provisions and joins a single machine in one step. Use this when you have SSH access to a fresh host and want to bring it into an existing network: 
ployzctl machine init user@10.0.1.20 \
  --network my-cluster \
  --runtime host \
  --service-mode system \
  --install-source release \
  --install-version latest
FlagDescription
--networkName of the cluster network to join (required)
--runtimeContainer runtime: docker or host
--service-modeHow ployzd runs: user or system
--install-sourceWhere to pull the binary from: release or git
--install-versionSpecific release version to install
--install-git-urlGit remote URL (used with --install-source git)
--install-git-refGit ref to build from (used with --install-source git)

​
Adding machines

machine add joins one or more machines into the cluster. It is the multi-target variant of machine init, and accepts the same install flags plus an optional SSH identity file:
1

Run machine add

Pass one or more SSH targets. Ployz will provision each in sequence.
ployzctl machine add \
  --network my-cluster \
  --runtime host \
  --service-mode system \
  user@10.0.1.21 user@10.0.1.22
2

Verify the result

Check that each new machine is visible and in the active lifecycle state.
ployzctl machine ls
3

Check RTT (optional)

Confirm that WireGuard peering is healthy by measuring round-trip times between machines.
ployzctl machine rtt
Pass --identity to specify an SSH private key file when the target requires a non-default identity.

​
Machine invite workflow

Use invites when you cannot provide SSH credentials to machine add — for example, when a new machine is bootstrapping itself into the cluster. The invite token is short-lived and single-use. On the cluster coordinator: 
# Create an invite token (default TTL: 600 seconds)
ployzctl machine invite create --ttl-secs 300

# List active invites
ployzctl machine invite list

# Revoke an invite before it is used
ployzctl machine invite revoke <invite-id>
On the joining machine: 
# Import the token; the machine joins the cluster network
ployzctl machine invite import --token <token>
The invite is consumed on import. Once a machine has joined, it appears in machine ls and can receive workloads.

​
Updating machines

machine update upgrades the ployzd binary on one or more machines to a target version: 
# Update specific machines
ployzctl machine update --version 0.4.2 <machine-id-1> <machine-id-2>

# Update all machines to the latest release
ployzctl machine update
The command reports which machines updated successfully and which failed, so partial failures are always visible.

​
Lifecycle transitions

Machines move through an explicit lifecycle. You control transitions with three commands:

activate

Marks the machine as ready to accept new workload placements.
ployzctl machine activate <machine-id>

drain

Stops new placements to this machine. Existing workloads keep running until you migrate or remove them.
ployzctl machine drain <machine-id>

standby

Removes the machine from active placement without draining running workloads immediately.
ployzctl machine standby <machine-id>
ployzctl machine standby --force <machine-id>
machine standby --force bypasses the precondition check that normally prevents a machine from entering standby while it still holds workloads. Use this when you need to park a machine that already has its workloads migrated manually.

​
Promoting storage authority

By default, only a subset of machines hold the full NATS control-plane store. machine storage promote adds machines to the storage authority set and configures the replication policy: 
ployzctl machine storage promote \
  --replicas 3 \
  <machine-id-1> <machine-id-2> <machine-id-3>
Machines must be active and on a compatible version. The command reports each promotion result individually, so you can see exactly which targets succeeded and which did not.
Storage-enabled nodes are trusted with the cluster’s control-plane secrets, including TLS private keys and ACME account keys. Treat storage machines the same as you would a root CA host.

​
Removing a machine

machine rm removes a machine’s membership record from the cluster: 
ployzctl machine rm <machine-id>
By default, the command attempts to clean up the machine’s on-device state — stopping workloads, leaving the mesh, and removing the daemon — before deleting the membership record. 
# Skip online cleanup and remove only the membership record
ployzctl machine rm --force <machine-id>
--force skips all online target cleanup. Use it when the machine is unreachable or already destroyed and you need to remove the stale membership record from the cluster.
Before removing a machine, drain its workloads first. Ployz will not automatically migrate workloads on removal — that decision belongs to you.

​
Next steps

Deploy workloads

Deploy services to your cluster after machines are joined and active.

Migrate workloads

Move a running workload and its persistent volumes to a different machine.

Build docs developers (and LLMs) love

Get started for freeTalk to us