shc node

Generate a join token for adding new nodes to the cluster:

shc node token
# Output: eyJ...base64-encoded-token...

The token includes:

• Leader address
• Bootstrap address list
• CA certificate
• Encrypted join credentials

With --swarm, show the Docker Swarm manager/worker join tokens instead (requires platform:manage) — for manually rejoining a host to the swarm layer. A cluster has exactly one swarm, so the tokens are cluster-wide; run this on a swarm manager:

shc node token --swarm
# MANAGER_TOKEN  SWMTKN-1-...
# WORKER_TOKEN   SWMTKN-1-...
# MANAGER_ADDR   10.0.0.5:2377
# hint: join a worker with `docker swarm join --token SWMTKN-1-... 10.0.0.5:2377`

Join an existing cluster using a token:

shc node join eyJ...token...

Options:

NIC selection (auto-detect):

• Deterministic: candidates sorted by interface name
• Private (RFC1918) addresses preferred over public
• Within the preferred class, the default-route interface wins
• Use --nic to override auto-detection (a nic that fails to resolve aborts the join)

# Auto-detect nic
shc node join eyJ...token...

# Pin the cluster-internal nic explicitly
shc node join eyJ...token... --nic eth1

On join, the node:

1. Receives cluster CA and node certificate
2. Joins the raft cluster (as voter or non-voter)
3. Starts SHC server with mTLS-authenticated internal API

Mesh membership is orchestrator-driven: after a join on a mesh-enabled cluster, re-run shc cluster mesh enable (additive + idempotent) to extend the overlay to the new node.

Gracefully leave the cluster:

shc node leave

This:

1. Drains workloads (if Swarm)
2. Syncs pending writes
3. Notifies other nodes
4. Converts back to SQLite

View cluster status:

shc node status

Shows:

• Cluster mode (single/cluster)
• Leader node
• All node states
• Quorum status

List nodes:

shc node ls
shc node ls -v                # Verbose output with extra details
shc node ls --output json

View node details:

shc node show node01

Shows:

• Node ID and address
• Role (leader/voter/non-voter)
• Health status
• Resource usage (CPU, memory, disk)

Check the health of a specific node:

shc node health node01

Shows:

• Node connectivity status
• Resource usage
• Service health

Drain workloads before maintenance:

shc node drain node01

Drain is an SHC-level deployment migration, not Docker Swarm’s native drain. Each running deployment on the node is relocated through the same path as shc move — backup, cross-node transfer, bring-up on the target, source teardown — and the node’s availability flips to drained only once every one of them has landed. With --force, a deployment that has nowhere to go is stopped in place instead of aborting the drain.

Because relocation is real work, budget accordingly: a node hosting several data-bearing stacks can exceed the default 300s timeout. Raise it with the request’s timeout field.

Candidate nodes are matched on runtime (a swarm deployment moves to another swarm node, a compose deployment to a compose node) and filtered by the deployment’s placement constraints. A service hard-pinned to the node being drained has no eligible target and is reported as failed with no node satisfies the deployment's placement constraints — unpin it, or pass --force to stop it in place.

If any deployment fails to migrate, the drain stops there and reports the per-stack reasons; the node is left draining, not drained, because it still hosts the workload. Fix the cause and re-run. The common case is the ingress entry point, which is refused by design — see the entry point section.

Remove an unreachable node:

shc node forget node01

Use when a node cannot gracefully leave.

Show the Docker Swarm join tokens held by a swarm manager node:

shc node swarm-tokens node01

Prints the manager and worker join tokens plus the manager address — for a manual docker swarm join. SHC-managed membership goes through shc node join.

Quorum-loss recovery moved. The emergency “force leader election” operation is now shc cluster repair --force — see cluster repair.

Initialize a new SHC cluster on the first node:

shc init

Options:

NIC selection (auto-detect):

• Deterministic: candidates sorted by interface name
• Private (RFC1918) addresses preferred over public
• Within the preferred class, the default-route interface wins
• Use --nic to override auto-detection

# Auto-detect nic
shc init

# Pin the cluster-internal nic explicitly (e.g., for dual-homed servers)
shc init --nic eth1

# Bring the Nebula mesh overlay up for cross-network connectivity
shc init --nebula

On init, SHC:

1. Generates cluster CA and node certificate
2. Initializes the state database
3. Starts SHC server with internal API
4. Installs system tenant apps (Traefik, OpenObserve)

• Cluster Commands - Cluster health and diagnostics
• Mesh Architecture - Service mesh overview
• Node Management