Joining nodes
A node joins with a token minted on a member. The token is single-use and
expires; --ttl sets how long it lives. Each join needs a fresh one, so each
runs on the joining node and asks home01 for its token over ssh:
shc node token --fields token -o text prints the token alone, and
shc node join - reads it from standard input, so it is never copied or
typed.
--control-plane puts the joiner in the control plane, the set of nodes
that may vote. home02 and home03 are in home, the location of the first
node, which is where the control plane starts; saying it makes it explicit.
--nic and --runtime are what init took on home01, typed with the values
the node would detect.
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home02 --cloud learn --location home --control-plane --nic eth0 --runtime docker✔ joined cluster as node "home02" at 192.168.232.12$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home03 --cloud learn --location home --control-plane✔ joined cluster as node "home03" at 192.168.232.13far01 is a worker in the other location. It joins with an operator label of
its own, tier=edge, which the placement page uses, and --public-address,
the address internet traffic reaches the node at, recorded on the node row
for managed DNS to read. far01’s is its hostname.
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01✔ joined cluster as node "far01" at 192.168.232.14A machine that also runs work outside SHC joins with --reserve, the
room it keeps for that work, as on shc init.
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01 --reserve cpu=1,memory=4Gi,disk=50GiA node that is a virtual machine joins with --hypervisor, the
connection its host is read through, as <connection>/<instance>. SHC reads
the host’s capacity and the other instances on it, never writes through it,
and takes off the node’s room what the host cannot give it. shc node update
sets it on a node that has joined, and an empty value clears it.
$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name far01 --cloud learn --location far --label tier=edge --public-address far01 --hypervisor pve/far01$ shc node update far01 --hypervisor pve/far01A join typed without the page’s flags lands under a random name,
worker- and eight letters, in the cloud and location the machine
reports, and the cluster keeps fewer voters than this page shows. Take
that node out from its own shell and click its join again. --force
because traefik already runs on every node, and a plain leave refuses a
node that hosts a deployment; the leader drops the node as it leaves.
$ shc node leave --force --yes$ ssh home01 shc node token --ttl 30m --fields token -o text | shc node join - --name home03 --cloud learn --location home --control-planeRun shc node ls again until every node reads healthy and ready.
$ shc node lsNAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTERfar01 healthy ready active learn learn/far ok 0.1.47 replica no nohome01 healthy ready active learn learn/home ok 0.1.47 voter yes yeshome02 healthy ready active learn learn/home ok 0.1.47 voter no yeshome03 healthy ready active learn learn/home ok 0.1.47 voter no yes$ shc cluster statuscluster name: shc-clusterleader: home01nodes: 4 healthy of 4voters: 3quorum: healthy, 2 voters requiredleader-only work, recorded by home01 41s ago:...shc node update --reserve sets that room on a node already in the
cluster, or changes it; a resource set to 0 clears it. Keep 1 GiB of
far01’s disk back, then give it back:
$ shc node update far01 --reserve disk=1Gi...$ shc node update far01 --reserve disk=0...Every node reaches every other over the mesh. Ping them all, then one.
$ shc cluster pingNODE STATUS RTTfar01 ok 34.74mshome01 ok 0.12mshome02 ok 1.22mshome03 ok 0.46ms$ shc cluster ping far01 -c 1 -T 2NODE STATUS RTTfar01 ok 34.85msThe licence meters the joins: four nodes of the ten it allows.
$ shc license statusstate: keyedtier: proholder: Learn walksource: filefeatures: audit, branding, clustering, console, container_runtime, environments, fleet, marketplace, mcp, multi_provider, quota, rbac, sso, support_bundle, tenancy
capacity: licensed: max_nodes=10 now: max_nodes=4 max_cores=8 max_seats=1 max_tenants=0 term peak: max_nodes=4 max_cores=8 max_seats=1 max_tenants=0 term began: 2026-11-06T17:07:03Zauto-check: onlast check: 2026-11-06T17:09:59Z, the broker did not answer, 1 failed attempt X502962LICRFRA new cluster holds one tenant, master, and the platform’s own apps live
there. Add prod, the tenant this ladder’s deployments go in, and select
it with shc ctx -t, as the app ladder does. Every later command on home01
then reads prod without naming it. --no-admin leaves the tenant’s
Keycloak realm without users, since no page here signs anyone in.
$ shc tenant add prod --no-admin✔ created tenant "prod"warning: keycloak realm provisioning still in progress$ shc ctx -t prod...The selection is home01’s own: a command typed on another node names its
tenant with -t. -t master lists the platform’s apps, and its traefik
now runs on every node. Leave prod selected throughout.
$ shc tenant lsACTIVE NAME DEPLOYMENTS master 3* prod 0$ shc ls -t masterSTACK TENANT ENV APP STATUS NODESkeycloak master default keycloak running home01postgres master default postgres running home01traefik master default traefik running far01, home01, home02, home03