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.
1. Get shc
Section titled “1. Get shc”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.
mkdir -p ~/shc-cli && cd ~/shc-clibase=https://downloads.selfhostedcloud.org/shc/devversion=$(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" >>~/.bashrceval "$line"command -v shcshc versioncommand -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:
ar x shc.debtar xf data.tar.*mkdir -p ~/shc-cli && cd ~/shc-clicase $(uname -m) in arm64) arch=arm64 ;; *) arch=amd64 ;; esacbase=https://downloads.selfhostedcloud.org/shcversion=$(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.gzline='export PATH="$HOME/shc-cli/bin:$PATH"'grep -qsxF "$line" ~/.zshrc || echo "$line" >>~/.zshrceval "$line"command -v shcshc versionThe 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.
Windows
Section titled “Windows”There’s no Windows build of shc. Use WSL2, which runs the Linux build:
- Open PowerShell as administrator and run
wsl --install. Restart if it asks you to. - Open Ubuntu from the Start menu and choose a username.
- Follow the Linux steps inside that window.
The sign-in below prints a link. Open it in your browser on Windows.
Update shc
Section titled “Update shc”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.
2. Sign in
Section titled “2. Sign in”Copy the command from your cluster’s card in the portal, or write it with your cluster’s address:
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-EFGHopening https://<your cluster's address>/auth/realms/master/device?user_code=ABCD-EFGHwaiting 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:
- Press Selfhosted Cloud Portal. Ignore the username and password form on that page. Your portal password doesn’t work there.
- Sign in to the portal if it asks.
- Allow access. The portal asks once per cluster.
- 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 active3. Run your first command
Section titled “3. Run your first command”shc lsYou 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.
Who can sign in
Section titled “Who can sign 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.
The certificate warning
Section titled “The certificate warning”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.
You rebuilt your cluster
Section titled “You rebuilt your cluster”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:
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.
On a phone
Section titled “On a phone”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.
When something goes wrong
Section titled “When something goes wrong”| What you see | What it means | What to do |
|---|---|---|
X400910DEVCFG no cluster url | You left out --url | Add --url https://<your cluster's address> |
X500913CAPINF with no such host | The cluster hasn’t registered, so its address doesn’t exist yet | Wait until its card reads registered |
X500913CAPINF with a 404 | --url names an IP address | Use the address from the card |
X409911CAPINC | The cluster’s certificate authority changed | See You rebuilt your cluster |
| A browser warning about the certificate | The cluster has no public certificate yet | See The certificate warning |
| ”Unexpected error when authenticating with identity provider” | Your portal role doesn’t allow it | See Who can sign in |
| ”Invalid username or password” | You typed into the form on the sign-in page | Press Selfhosted Cloud Portal instead |
X408910DEVEXP | The code expired | Run shc auth login again and finish sooner |
X401903NOSESS | You aren’t signed in | Run shc auth login --url https://<your cluster's address> |
X200962CLIOLD | Your shc is older than the cluster | See Update shc |
command -v shc prints /usr/bin/shc | An older install comes first on your PATH | Open 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 machine | Run shc auth login --url https://<your cluster's address> |