Skip to content
SHC Docs

Reach a portal cluster from your laptop

The portal built your cluster and keeps its SSH key. You don’t need that key. You sign in over HTTPS with your portal account and run shc from your own machine.

You need three things:

  • A cluster whose card in the portal reads registered. Its address is on that card, and looks like test-yourname-0911-1a2b3c4d.dev.clusters.selfhostedcloud.org.
  • To be a registrant, owner or admin of the organization that owns it. See Who can sign in.
  • A laptop or desktop that can reach port 443. See On a phone if a phone is all you have.

Don’t use the install line from the portal’s wizard. It sets up a whole server and changes your Docker settings. These steps unpack shc into one folder and install nothing.

The commands fetch the dev build, which is what a cluster on my.dev.selfhostedcloud.org runs. On the production portal, write shc where they say shc/dev.

Each block puts that folder first on your PATH, for this window with export and for every new window through your shell’s startup file. It comes first so an older shc somewhere else, from the install line or an earlier round, never answers in its place.

Terminal window
mkdir -p ~/shc-cli && cd ~/shc-cli
base=https://downloads.selfhostedcloud.org/shc/dev
version=$(curl -fsS "$base/RELEASE")
arch=$(dpkg --print-architecture)
curl -fsSLo shc.deb "$base/$version/shc_${version}_linux_$arch.deb"
dpkg-deb -x shc.deb .
line='export PATH="$HOME/shc-cli/usr/bin:$PATH"'
grep -qsxF "$line" ~/.bashrc || echo "$line" >>~/.bashrc
eval "$line"
command -v shc
shc version

command -v shc prints /home/<you>/shc-cli/usr/bin/shc. If your shell is zsh, write ~/.zshrc for ~/.bashrc.

No dpkg on your distribution? Write arch=amd64 or arch=arm64 in place of the dpkg --print-architecture line, and these two in place of the dpkg-deb line:

Terminal window
ar x shc.deb
tar xf data.tar.*
Terminal window
mkdir -p ~/shc-cli && cd ~/shc-cli
case $(uname -m) in arm64) arch=arm64 ;; *) arch=amd64 ;; esac
base=https://downloads.selfhostedcloud.org/shc
version=$(curl -fsS "$base/dev/RELEASE")
curl -fsSLo shc.tar.gz "$base/dev/$version/shc_${version}_darwin_$arch.tar.gz" || {
version=$(curl -fsS "$base/RELEASE")
curl -fsSLo shc.tar.gz "$base/$version/shc_${version}_darwin_$arch.tar.gz"
}
tar xzf shc.tar.gz
line='export PATH="$HOME/shc-cli/bin:$PATH"'
grep -qsxF "$line" ~/.zshrc || echo "$line" >>~/.zshrc
eval "$line"
command -v shc
shc version

The dev channel may not carry a Mac build. When it doesn’t, the curl prints a 404 error and the block fetches the current release instead. A release build signs in to a dev cluster and runs shc ls, but it won’t know a command added since that release.

There’s no Windows build of shc. Use WSL2, which runs the Linux build:

  1. Open PowerShell as administrator and run wsl --install. Restart if it asks you to.
  2. Open Ubuntu from the Start menu and choose a username.
  3. Follow the Linux steps inside that window.

The sign-in below prints a link. Open it in your browser on Windows.

Run your block again. It fetches the newest build into the same folder, and shc version then names it. Do this when the cluster is newer than your shc: an older shc still signs in, then sends requests the cluster can refuse.

The install line from the wizard is separate. It put a package on that machine once, and nothing brings that package a newer version unless apt took it from the Based repo, which only the production line does, on Debian 13. On a machine with both, the folder here comes first on your PATH, so the package’s shc never answers. To update the package too, run the install line again. It upgrades the package in place.

Copy the command from your cluster’s card in the portal, or write it with your cluster’s address:

Terminal window
shc auth login --url https://<your cluster's address>

shc prints the cluster’s certificate fingerprint, then a link and a code:

pinned cluster CA sha256:EF:6B:EB:...
to authenticate, visit https://<your cluster's address>/auth/realms/master/device and enter code ABCD-EFGH
opening https://<your cluster's address>/auth/realms/master/device?user_code=ABCD-EFGH
waiting for authorization...

It opens your browser if it can. If it can’t, open the link yourself in any browser, on any device, including your phone.

In the browser:

  1. Press Selfhosted Cloud Portal. Ignore the username and password form on that page. Your portal password doesn’t work there.
  2. Sign in to the portal if it asks.
  3. Allow access. The portal asks once per cluster.
  4. Press Yes when the page asks you to grant access to the command line.

The terminal then says:

logged in to "https://<your cluster's address>" in realm "master"; cluster "<your cluster's address>" is now active
Terminal window
shc ls

You get a table of what runs on the cluster. A new cluster already runs a few system deployments, such as keycloak and traefik. You’re in.

A registrant, owner or admin of the organization that owns the cluster gets full control of it.

A member or viewer can’t sign in. They press Selfhosted Cloud Portal, allow access, and land on a page that says “Unexpected error when authenticating with identity provider”. No account is made on the cluster. That’s the page working as intended, so ask an owner to change your role.

Your browser may warn about the certificate on your cluster’s pages. A new cluster asks Let’s Encrypt for a certificate once it’s up, and retries after 5, 10, then 20 minutes when the first try fails, so expect the warning for up to about 40 minutes. Carry on past it. The shc command doesn’t care, because it trusts the fingerprint it printed.

Let’s Encrypt gives one name five certificates a week, and fifty a week across all these clusters. A cluster past either limit keeps the warning until the limit refills. That’s a warning and not a failure: everything else still works.

A cluster rebuilt under the same name has a new certificate authority, and shc refuses it with X409911CAPINC. Forget the old one and sign in again:

Terminal window
shc ctx logout <your cluster's address>
shc auth login --url https://<your cluster's address>

Only do this for a cluster you rebuilt. If you didn’t, find out why the fingerprint changed before you sign in.

You need a terminal for this. shc doesn’t run on a phone, so a phone alone can’t get shc, start the sign-in or run shc ls.

A phone can finish the browser part. Start shc auth login on any computer, then open the link on your phone.

The TUI tile in the cluster’s console is a status display and not a shell, so it doesn’t replace a terminal. For anything else on a phone, use Open console on the cluster’s card.

What you seeWhat it meansWhat to do
X400910DEVCFG no cluster urlYou left out --urlAdd --url https://<your cluster's address>
X500913CAPINF with no such hostThe cluster hasn’t registered, so its address doesn’t exist yetWait until its card reads registered
X500913CAPINF with a 404--url names an IP addressUse the address from the card
X409911CAPINCThe cluster’s certificate authority changedSee You rebuilt your cluster
A browser warning about the certificateThe cluster has no public certificate yetSee The certificate warning
”Unexpected error when authenticating with identity provider”Your portal role doesn’t allow itSee Who can sign in
”Invalid username or password”You typed into the form on the sign-in pagePress Selfhosted Cloud Portal instead
X408910DEVEXPThe code expiredRun shc auth login again and finish sooner
X401903NOSESSYou aren’t signed inRun shc auth login --url https://<your cluster's address>
X200962CLIOLDYour shc is older than the clusterSee Update shc
command -v shc prints /usr/bin/shcAn older install comes first on your PATHOpen a new terminal, or run your block again
X502739DMNLST ending in “run shc auth login --url <cluster>”You aren’t signed in, so shc looked for a server on your own machineRun shc auth login --url https://<your cluster's address>