> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rafftechnologies.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect via SSH
> Open a session to a Linux VM — in-browser terminal, direct SSH, or VNC console fallback
Updated May 8, 2026
Once a Linux VM is `active`, you have three ways to connect:
| Method | Where it runs | Best for |
| -------------------- | -------------------------------- | ------------------------------------------------------------- |
| **Browser terminal** | In the dashboard | One-off checks; no client install |
| **Direct SSH** | Your machine (terminal or PuTTY) | Daily use, scripts, file transfer |
| **VNC console** | In the dashboard | Fallback when networking is broken or the VM has no public IP |
The dashboard's **Console** button picks the right in-app option automatically:
* **Public IPv4 exists and SSH not disabled** → SSH browser terminal opens.
* **No public IPv4, or SSH disabled** → VNC console opens instead.
## 1. Browser terminal (in-app SSH)
You can open it from three places.
### a. VM detail page → Console
The big orange **Console** button at the top of any VM's detail page.
### b. Instances list → row's 3-dot menu → Open Terminal
Click the **⋮** at the right end of any VM row, then **Open Terminal**.
### c. VM detail page → Actions tab
The same Console action also appears under the **Actions** tab on the detail page — useful when you've scrolled past the top action bar.
### What you see
The terminal opens in a new tab, authenticates as `root` automatically using the VM's stored credentials, and drops you at a shell. **Fullscreen** and **Disconnect** are top-right.
## 2. Direct SSH (your terminal or PuTTY)
For daily work, scripts, file transfer (`scp`/`rsync`), port forwarding, etc.
### Generate an SSH key (if you don't have one)
If you don't already have an SSH key pair on your local machine, generate one before creating the VM. Pick the matching command for your OS — the resulting public key is what you upload to Raff at VM creation, and the private key stays on your machine.
**macOS / Linux / Windows OpenSSH (PowerShell):**
```bash theme={null}
# Recommended — Ed25519, modern, fast, short
ssh-keygen -t ed25519 -C "you@example.com" -f ~/.ssh/raff_key
# Acceptable fallback if a tool requires RSA
ssh-keygen -t rsa -b 4096 -C "you@example.com" -f ~/.ssh/raff_key
```
When prompted:
* **Passphrase** — set one. It encrypts the private key on disk so a stolen laptop can't be used to log in. Use `ssh-agent` (`ssh-add ~/.ssh/raff_key`) so you only type it once per session
* Two files are written:
* `~/.ssh/raff_key` — **private** key. Never share, never paste into a web form, never commit to git
* `~/.ssh/raff_key.pub` — **public** key. This is what you paste into Raff's **SSH Keys** dialog when creating a VM
Print the public key to copy it:
```bash theme={null}
cat ~/.ssh/raff_key.pub
```
Output looks like `ssh-ed25519 AAAAC3Nza... you@example.com` — copy the entire line into Raff's SSH Keys field.
### macOS / Linux — terminal
```bash theme={null}
ssh root@
```
If you set up the VM with **SSH Key** auth, your matching private key authenticates automatically (e.g. `~/.ssh/id_ed25519`). If you used **Password** auth, you'll be prompted.
To use a specific key file:
```bash theme={null}
ssh -i ~/.ssh/raff_key root@
```
If you get **Permission denied (publickey)**, fix key permissions: `chmod 600 ~/.ssh/raff_key`.
### Windows — PuTTY
1. Download PuTTY from [putty.org](https://www.putty.org).
2. In **Host Name (or IP address)**, paste the VM's public IPv4. Port `22`, connection type **SSH**.
3. For SSH-key auth: open **Connection → SSH → Auth → Credentials** and browse to your `.ppk` private key. If you only have an OpenSSH-format key, convert it first using **PuTTYgen** (Load → Save private key as `.ppk`).
4. Click **Open**. Username `root`. PuTTY uses the key, or prompts for the password.
### Windows — built-in OpenSSH (Windows 10+ / 11)
PowerShell or Command Prompt — same as macOS/Linux:
```powershell theme={null}
ssh root@
```
Works if your private key is at `%USERPROFILE%\.ssh\id_ed25519` (or similar).
### Avoiding the "host authenticity" prompt with `ssh-keyscan`
The first time you SSH to a new VM, OpenSSH prints something like:
```
The authenticity of host '203.0.113.10' can't be established.
ED25519 key fingerprint is SHA256:abc...xyz
Are you sure you want to continue connecting (yes/no)?
```
Typing `yes` is fine for interactive use, but for **automation, CI/CD, or scripted provisioning** that prompt blocks the script. Pre-populate `~/.ssh/known_hosts` with the VM's host key before connecting:
```bash theme={null}
# Fetch the VM's public host keys and append to known_hosts
ssh-keyscan -H >> ~/.ssh/known_hosts
```
`-H` hashes the entry so the IP isn't visible in plaintext if the file is leaked. Run once per VM after creation; subsequent SSH calls will not prompt.
For Ansible / Terraform `remote-exec` provisioners, run `ssh-keyscan` as part of your bootstrap step right after the VM becomes `active`.
## 3. VNC console (graphical fallback)
The VNC console connects through the hypervisor instead of the network. Use it when:
* The VM has **no public IPv4** (private-only VPC)
* You misconfigured the firewall or security group and locked yourself out over SSH
* The SSH daemon isn't running or you've disabled it
* You need single-user mode or to recover from a broken boot
Open it the same way as the browser terminal — **Console** button on the detail page, or **Open Terminal** on the row Actions menu. When SSH isn't reachable, the dashboard automatically opens VNC instead and shows the OS login prompt.
Close the browser tab to disconnect.
## Troubleshooting
* **Connection refused** — the attached security group must allow inbound TCP/22 from your IP.
* **Permission denied (publickey)** — verify your private key matches the public key uploaded at VM creation; on macOS/Linux make sure the key permissions are `600`.
* **Connection timed out** — check the VM is `active`, not `passive` or `provisioning`. Confirm the public IPv4 in the dashboard hasn't changed.
* **No public IP** — use the VNC console, or reach the VM through another VM in the same VPC.
* **`REMOTE HOST IDENTIFICATION HAS CHANGED!`** — the VM's host key changed (typically after a Reinstall, factory reset, or new VM at the same IP). Remove the stale line: `ssh-keygen -R `, then reconnect (or re-run `ssh-keyscan` for automation).
See [Troubleshooting](/products/build/virtual-machines/troubleshooting) for more.
## Next steps
Start, stop, reboot.
Recover access if you're locked out.