Connecting via SSH

Every pod is a full Linux system you can log into. SSH works the way you'd expect, with one twist: from the public internet you connect on a mapped external port, not the standard port 22.

Three things have to line up before a login works: the connection details, something to authenticate with, and a firewall that lets your address through. Each one has its own screen in the console, and every click is named below.

What you need first

• A pod that is Running.
• A way in: an SSH key attached to the pod, or the one-time login password. More on both just below.
• An IP address the pod's firewall allows. Step 2 covers that.

The cleanest path is to add an SSH key when you create the pod. Don't have one yet:

ssh-keygen -t ed25519 -C "you@laptop"
cat ~/.ssh/id_ed25519.pub

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJd3Ff0T8kZk7g2CqQ0mJ2sV6vB5xTn9pLcR1yWqA4eH you@laptop

Paste that whole line into SSH Public Key (optional) on the Create Pod page, or pick a key you have used before from the Select a saved SSH key dropdown. Pasted keys are saved for next time, so the dropdown only appears once you have one. RSA, Ed25519, ECDSA and the hardware-backed sk- variants are accepted. Then you log in with your key and there is no password to manage at all.

If you don't add a key, an Ubuntu pod gets a generated login password instead. It is shown once, in the toast in the bottom-right corner after you click Create Pod ("Auto-generated password: ..."), and never again. The toast clears itself after about five seconds, so hover over it to stop the clock while you copy. That password is also expired the moment it is created, so the first time you use it, SSH makes you set a new one before it gives you a prompt.

Instance pods can't reset their login password

There's no "reset password" for Ubuntu pods. If you lose the one-time password and never added a key, don't panic - use the browser Shell to get in (it doesn't need the password), then add your public key to the login user's authorized_keys. From then on you log in with the key. Reset password exists only for database pods (see below).

1. Find your connection details

1. Open Pods in the console, or click Pods in the side panel.

2. Click the pod's name in the table. You land on the pod's page, on the Overview tab.

3. The first card is Access, and it hands you the finished command:

   ssh -p 3001 [email protected]

   Click it to copy. Under it are the same pieces labelled one by one - Username, Public Host, Ports (one chip marked private, the internal service port, one marked public, the number you pass to -p) and the pod's Firewall, which is a link straight to step 2. Click any value to copy it.

A MySQL pod's Access card holds a mysql command instead, built the same way.

The Connection Strings tab has the same public command in a Public SSH card, plus the one the Access card doesn't show:

• Private SSH - ssh ubuntu@i-6a4d5b83b7006ccae6391810, for connecting from another pod on the same private network.

A MySQL pod gets Public MySQL and Private MySQL cards there instead.

Two more values live on the Networking tab, in the Private Network card: Hostname (that generated i-... name, which is not the name you gave the pod) and Private IP.

Pods in the same Region share one public host. The external port is the part that belongs to your pod alone, which is why -p is not optional:

ssh [email protected]          # wrong: port 22 is not yours
ssh -p 3001 [email protected]  # right

2. Let your IP through the firewall

A pod created without picking a firewall gets one that blocks all public traffic. Your ssh will sit there and then give up, with nothing useful to say about why:

ssh: connect to host your-pod.microapps.io port 3001: Connection timed out

That is the firewall, not the pod. (The in-browser Shell works regardless.)

1. On the pod's page, open the Overview tab and click the firewall's name in the Access card's Firewall row. You land on that firewall's page. (The Networking tab's Security & Public Access card has the same link.)
2. Click New Rule, at the top right. An Add Rule form opens above the rules.
3. Fill in IP Address / Network - 203.0.113.42/32 for a single address - and a Description you will still recognise in six months. Click Add.
4. Click Apply Changes, at the top right. Until you do, the rule only exists in your browser, and the header says Unsaved changes.

Rules take effect within seconds, no reboot.

3. Log in

Paste the command from the Access card. On a key-based pod that is the whole ceremony. On a password pod, the first login is also a password change:

$ ssh -p 3001 [email protected]
The authenticity of host '[your-pod.microapps.io]:3001' can't be established.
ED25519 key fingerprint is SHA256:9xK2vQ7pMnB4eR1sT6uY0wZ3aC5dF8gH2jL4nP6qS8w.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
[email protected]'s password:
You are required to change your password immediately (administrator enforced).
Changing password for ubuntu.
Current password:
New password:
Retype new password:
Welcome to Ubuntu 24.04.3 LTS (GNU/Linux 6.8.0-79-generic x86_64)

ubuntu@i-6a4d5b83b7006ccae6391810:~$

The prompt shows the pod's generated hostname, not the name you gave it. You are in.

Adding an SSH key to an existing pod

If you didn't add a key at creation, add one now:

1. Get in once - over SSH with the login password, or through the browser Shell.
2. Append your public key to the login user's authorized_keys. Swap ubuntu below for the pod's Username from the Access card. The path is written out in full so the key lands in that user's home directory whichever user your session happens to be:

   sudo mkdir -p /home/ubuntu/.ssh
   echo "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIJd3Ff0T8kZk7g2CqQ0mJ2sV6vB5xTn9pLcR1yWqA4eH you@laptop" \
     | sudo tee -a /home/ubuntu/.ssh/authorized_keys
   sudo chmod 700 /home/ubuntu/.ssh
   sudo chmod 600 /home/ubuntu/.ssh/authorized_keys
   sudo chown -R ubuntu:ubuntu /home/ubuntu/.ssh

3. From now on, ssh -p 3001 [email protected] uses your key.

Keys you save on the account are listed by the SSH keys API, and you can attach one to the next pod you create without pasting it again.

Connecting from another pod on the same network

When two pods share a private network, they reach each other directly on internal ports (no mapping) by private hostname:

ssh ubuntu@i-6a4d5b83b7006ccae6391810

That name is the Hostname from the other pod's Networking tab, Private Network card - the same value its Private SSH connection string uses. It is generated, so it is not the pod's name. Port 22 is the default, so no -p here. Same goes for other services: MySQL on 3306, HTTP on 80, your app on 3000. Same-network neighbours use the real internal port.

Resetting a database password

Database pods only. If you lose a database pod's password:

1. Open Pods and click the database pod's name in the table.
2. Click the ... button at the top right of the pod's page.
3. Choose Reset password. The dialog warns you that the new password is shown once and cannot be recovered; click Reset password again to confirm.

A fresh password is generated and shown in the toast in the bottom-right corner. Copy it there and then - it is not shown again. (Via the API: POST /api/pods/:id/reset-password.) On an Ubuntu pod the menu item isn't there at all.

Locking SSH down to your IP

You probably don't want SSH open to the world. See Networks and firewalls - a firewall that allows only your home or office IP closes every public port, SSH included, to everyone else. (Firewall rules are per-IP, not per-port.)

When SSH isn't an option

On a network that blocks outbound SSH? Use the browser Shell instead. It runs over the same connection as the console, so port mapping doesn't apply - it just works. (Instance pods only.)