Quick start
Seven short steps from a bare Linux box to a running app with a backup, one binary, no external services. Step 2 is optional; everything else works on a single node.
1. Initialize the cluster
Section titled “1. Initialize the cluster”First, initialize SHC on your node:
# Initialize with auto-detected network interfaceshc init
# Or pin the underlay NIC for dual-homed serversshc init --nic eth1This bootstraps the node with its cluster CA and certificate, control-plane
database and systemd services. The node plane is mesh0 (kernel WireGuard,
UDP 4244); use shc cluster mesh status to inspect it.
✔ You now have a working one-node cluster. Next: give it company, or skip ahead, the rest works fine on one machine.
2. Add more nodes (optional)
Section titled “2. Add more nodes (optional)”To add nodes to the cluster:
# On the first node, generate a join tokenshc node token
# On the new node, join the clustershc node join <token>Licence check first. Clustering is a Pro-tier feature (
TIERS.md, “Pro tier”). A free estate, and the 30-day trial, which grants Hobby and one node (“The trial line”), cannot admit a second node: the join is refused withX403029LICENT clusteringand leaves the new host untouched.shc license statusshows what this estate carries.
✔ You now have a multi-node cluster. Two nodes add capacity, not fault tolerance: repeat the join for a third node and the control plane has three voters, so it can lose a machine and keep quorum. Next: prove it’s healthy.
3. Check cluster health
Section titled “3. Check cluster health”# View cluster statusshc cluster status
# List all nodesshc cluster nodes✔ You now have a verified control plane. Next: make it earn its keep.
4. Install your first app
Section titled “4. Install your first app”whoami is a tiny request-inspection app, the fastest way to watch a full
deploy end to end.
Every app lives in a tenant. A cluster made through the portal already has
one named default. On a cluster you installed yourself, shc tenant ls
lists only master, SHC’s own, so first run shc tenant add default, which
is free (Tenants has the rest). Select it with
shc ctx -t, so every command on the rest of this page runs in it.
--expose gives the app its web address; replace whoami.example.com with a
name in your own domain. Without it the app runs with no address at all.
# See your tenants and select defaultshc tenant lsshc ctx -t default
# Install a simple app and give it an addressshc install whoami --expose whoami.example.com
# Check statusshc status whoami✔ You now have an app serving from your own hardware. Next: the three commands you’ll use every day.
5. Watch it run
Section titled “5. Watch it run”# List all stacksshc ls
# View deployment and service healthshc status
# View logsshc logs --stack whoami --follow✔ You now have the daily operator loop: list, status, logs. Next: make sure the data outlives the app.
6. Back it up
Section titled “6. Back it up”# Create backupshc backup create --stack whoami
# List backupsshc backup ls --stack whoamiThe backup stages the stack’s data into a .bak archive and stores it in a
Restic repository, deduplicated and incremental. shc backup restore
brings it back any time.
✔ You now have a restorable backup. Next: leave the campsite clean.
7. Clean up
Section titled “7. Clean up”# Uninstallshc uninstall whoami✔ You now have a clean cluster again, and you’ve run the full lifecycle: init, join, install, observe, back up, remove.
Where next
Section titled “Where next”If any step above stopped (the package would not install, shc ls found no
apps to install, or an --expose resolved to nothing), read
After shc init. It covers the four gaps a fresh cluster
has that this page assumes away.
Three good next moves, in rising order of commitment:
- Add a node: Multi-node cluster setup covers prerequisites, join, and which state becomes cluster-wide.
- Install a real app: browse the app catalog: Keycloak, Postgres, GitLab, Immich, and the rest.
- Set up real backups: backup commands
for restore, export, and verify;
shc retentionfor retention policies.
Or read Core concepts first: tenants, environments, stacks, and how they fit together.