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:

# Initialize with auto-detected network interface
shc init

# Or pin the cluster-internal nic for dual-homed servers
shc init --nic eth1

This bootstraps the node — the cluster CA, this node’s certificate, the local control-plane database, and the systemd services. The Nebula mesh overlay is opt-in: add --nebula (or run shc cluster mesh enable later) only when you need an encrypted cross-network underlay between nodes. A single node or a LAN cluster does not need 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:

# On the first node, generate a join token
shc node token

# On the new node, join the cluster
shc node join <token>

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

# 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:

# Install a simple app
shc install whoami

# Check status
shc status whoami

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

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

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

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

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 retention for retention policies.

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