Docs

Quickstart

By the end of this page you will have a device you can open a shell on from anywhere, in the browser or in your own SSH client. Nothing on the device listens for inbound connections.

Create your account

  1. Sign up with a name, a username, an email and a password, and accept the privacy policy.
  2. Click the link in the confirmation email. Until you do, signing in returns you to the confirmation screen, which can send the email again.
  3. Sign in.

The console opens on Get your first shell, a page that takes you through the rest of this guide one step at a time: your namespace, the agent, the pairing and the first shell. On Cloud it first asks a few questions about you. Leave it before pairing and it picks up where you stopped.

A namespace is what devices join. Its name is part of every address you use to reach a device, so keep it short: 3 to 30 characters, lowercase letters, numbers and hyphens.

Connect your device

A device is any machine running the agent. The agent opens one outbound connection to the server and keeps it, which is what lets you reach the device through a NAT you do not control.

Install the agent

The Install the agent step shows the command. Run it on the machine you want to reach:

$ curl -sSf https://cloud.shellhub.io/install.sh | sh

The installer picks a method on its own: Docker, then Podman, then Snap, then WSL, then a native binary under systemd. To choose yourself, see Choosing a Method.

Pair it

Given no credentials, the installer runs shellhub-agent login, which asks the server for a code, prints it, and waits:

To accept this device, open the ShellHub console and enter this code:

      4KQP-7M2X

Enter it at https://cloud.shellhub.io/accept-device, or open the link:

  https://cloud.shellhub.io/accept-device?code=4KQP7M2X

Waiting for acceptance... (code expires in 10 minutes)

Where xdg-open is available, it also opens the link in the browser for you.

  1. Type the code into the Pairing code field, or paste the whole link, and continue.
  2. Check the device it found against the machine you are expecting: hostname, operating system, MAC address, agent version and the code itself.
  3. Click Pair into your namespace. If it is not your machine, click Not this one.

Opening the link instead shows a page of its own with the code, hostname, operating system and MAC address. Pick the namespace there and click Accept device:

The agent stops waiting, joins the namespace and connects. There is no second command to run.

Open a shell in the browser

  1. Click Open terminal in the last step of the page. If you have left the page since, open the device from Devices and click Connect.
  2. Check the login. It starts as root, and you can type any other.
  3. Click Open in browser.

The first time, the console asks to register the browser. It generates an SSH key that never leaves the browser and adds it to your SSH Identities under the name you give it. After that, the browser connects without asking, and you can revoke the key there whenever you like.

Nothing else had to be set up. Your namespace starts with one access policy, Owner access, which lets you in as any login on every device.

Open it in your own terminal

The same panel has Open in external terminal. It is an ssh:// link, so your system hands it to the SSH client it has registered for that kind of link. The command behind it is the device’s SSHID, which you can also run by hand:

$ ssh <login>@<namespace>.<device>@cloud.shellhub.io

The namespace and the device are part of the hostname, so an ordinary client reaches the right machine through the one server that is listening.

The first connection with a key stops rather than opening. The server has never seen the key and has no signed-in session to tell it whose key it is, so it prints a link and waits:

  ShellHub doesn't know this SSH key yet.

  Open the link to add it to your identities:

    https://cloud.shellhub.io/ssh-identities/new/2HP6S9DZ

  Security code:  2HP6 S9DZ
  Key:            SHA256:vXV24Lb0Uiy6jRbJ2ns7uFAgrfzS6qT1KPvu6MwKqCQ

  The console gives you a confirmation code once you add it.

Confirmation code:
  1. Open the link in the browser you are signed in to, open Login details, check that its code matches the security code in your terminal, and click Add key.
  2. Type the confirmation code the console shows at the Confirmation code: prompt.

The shell opens, and the key is now one of your SSH identities. Every later connection with it goes straight through with stock OpenSSH. The link lasts 90 seconds. If it runs out, connect again for a new one.

Where to go next

esc