Skip to content
SHC Docs

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.

First, initialize SHC on your node:

Terminal window
# Initialize with auto-detected network interface
shc init
# Or pin the underlay NIC for dual-homed servers
shc init --nic eth1

This 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.

To add nodes to the cluster:

Terminal window
# On the first node, generate a join token
shc node token
# On the new node, join the cluster
shc 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 with X403029LICENT clustering and leaves the new host untouched. shc license status shows 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.

Terminal window
# View cluster status
shc cluster status
# List all nodes
shc cluster nodes

✔ You now have a verified control plane. Next: make it earn its keep.

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.

Terminal window
# See your tenants and select default
shc tenant ls
shc ctx -t default
# Install a simple app and give it an address
shc install whoami --expose whoami.example.com
# Check status
shc status whoami

✔ You now have an app serving from your own hardware. Next: the three commands you’ll use every day.

Terminal window
# List all stacks
shc ls
# View deployment and service health
shc status
# View logs
shc logs --stack whoami --follow

✔ You now have the daily operator loop: list, status, logs. Next: make sure the data outlives the app.

Terminal window
# Create backup
shc backup create --stack whoami
# List backups
shc backup ls --stack whoami

The 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.

Terminal window
# Uninstall
shc uninstall whoami

✔ You now have a clean cluster again, and you’ve run the full lifecycle: init, join, install, observe, back up, remove.


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:

Or read Core concepts first: tenants, environments, stacks, and how they fit together.