Skip to content
SHC Docs

SHC Desktop

SHC Desktop is the SHC console in a desktop window, on Linux and macOS. It opens the console your cluster already serves, so you sign in through your cluster’s own sign-in and see the same console a browser shows, updates included. It works with any SHC cluster; none is built in.

On Debian trixie or BasedOS d13, amd64 or arm64, with the Based apt source set up:

Terminal window
sudo apt install shc-desktop

Each release also puts the packages under https://downloads.selfhostedcloud.org/shc/<version>/desktop/:

FileFor
shc-desktop_<version>_linux_amd64.debLinux on Intel or AMD
shc-desktop_<version>_linux_arm64.debLinux on ARM
shc-desktop_<version>_darwin_arm64.dmgmacOS on Apple silicon, signed and notarized, once a release carries it

Install a downloaded deb with sudo apt install ./shc-desktop_<version>_linux_<arch>.deb so apt pulls in WebKitGTK.

The first launch asks for the cluster’s address: the host its console answers on, like shc.example.com. Type the host alone and SHC Desktop uses https. Every cluster you connect to is remembered, and the next launch opens the last one.

SHC Desktop > Switch cluster… (Ctrl+Shift+K, or ⌘⇧K on a Mac) goes back to the list. Pick another cluster there, add a new one, or forget one with ✕.

The list is a small JSON file you can delete to start over:

SystemFile
Linux~/.config/com.selfhostedcloud.desktop/clusters.json
macOS~/Library/Application Support/com.selfhostedcloud.desktop/clusters.json

The console comes from your cluster, so updating the cluster updates what SHC Desktop shows, on its next load. The app around it (the window, the menu and the cluster list) updates with sudo apt upgrade on Linux, or a newer dmg on macOS.

TargetWhat it does
make desktop/debBuilds both debs in docker/desktop-build (amd64 natively, arm64 cross-compiled) into build/desktop/, after the app’s unit tests
make desktop/smokeInstalls the amd64 deb on a bare Debian trixie and runs it on a virtual screen: first run opens the picker, connecting remembers the cluster, Switch cluster returns to the picker, a relaunch opens the last cluster. Screenshots land in build/desktop-smoke/. DESKTOP_SMOKE_CLUSTER=https://shc.example.com also opens a real cluster
make desktop/macosOn a Mac with Xcode: builds, signs with the team’s Developer ID Application identity, notarizes and staples the app and the dmg. Needs ASC_KEY_ID, ASC_ISSUER_ID and ASC_KEY_PATH, the App Store Connect API key

CI runs the same three as jobs of the same names. desktop/deb and desktop/smoke run on a push to main that touches apps/desktop, docker/desktop-build or scripts/desktop-*, and on every release tag. Pipelines on next run only next/* jobs, so a merge request into next doesn’t build the app; run make desktop/deb desktop/smoke for that. desktop/macos runs on a release tag once the project sets SHC_DESKTOP_MACOS=true and a runner tagged macos exists. A release tag then publishes the files to the downloads tree (pulp/shc-desktop) and the debs to the Based apt repo (pulp/shc-desktop-apt).