openboatmobile-ai/docs/SSH_GUIDE.md

# SSH for Clients

**A simple guide to connecting to your server remotely.**

## What is SSH?

SSH (Secure Shell) is a way to control a computer from somewhere else. Think of it like remotely driving a car — you're in the driver's seat, but the car is somewhere else.

When you SSH into a server, you get a command line on that server. You can run commands, install software, check logs — everything you could do if you were physically sitting at that computer.

## Why Do You Need It?

For your OpenBoatmobile deployment, SSH is how you:

- Check if everything is running correctly
- View logs when something goes wrong
- Run maintenance commands
- Update configurations

## The Key Concept: Lock and Key

SSH uses two files that work together:

| File | Analogy | Where it lives |
|------|---------|----------------|
| **Private key** | Your house key | Your computer, never share |
| **Public key** | Your lock | The server, you can share |

**The private key stays with you.** The public key goes on the server.

When you connect, SSH checks: *Does your private key match the public key on the server?* If yes, you're allowed in. If no, access denied.

**Important:** Your private key is like your house key. Don't give it to anyone. Don't email it. Don't upload it anywhere.

## Step-by-Step: Setting Up SSH

### macOS / Linux

**1. Generate your keys:**

Open Terminal and run:

```bash
ssh-keygen -t ed25519 -C "your-email@example.com"
```

When prompted:
- Press Enter to accept the default location (`~/.ssh/id_ed25519`)
- Press Enter twice for no passphrase (or set one if you want extra security)

**2. See your public key:**

```bash
cat ~/.ssh/id_ed25519.pub
```

Copy the entire output — it starts with `ssh-ed25519` and ends with your email.

**3. Add your key to the cloud provider:**

**Hetzner:**
1. Go to [console.hetzner.cloud](https://console.hetzner.cloud/)
2. Navigate to Security → SSH Keys
3. Click "Add SSH Key"
4. Paste your public key
5. Give it a name (like "my-laptop")
6. Click "Add SSH Key"

**DigitalOcean:**
1. Go to [cloud.digitalocean.com](https://cloud.digitalocean.com/)
2. Navigate to Account → Security
3. Click "Add SSH Key"
4. Paste your public key
5. Give it a name
6. Click "Add SSH Key"

**4. Test your connection:**

After your server is deployed (via Terraform), connect:

```bash
# Username is 'openclaw' or 'hermes' depending on your framework
ssh <USERNAME>@your-server-ip
```

If successful, you'll see a command prompt from the remote server.

### Windows

**Option 1: PowerShell (Windows 10/11)**

Open PowerShell and follow the macOS/Linux steps above. Windows now includes OpenSSH by default.

**Option 2: PuTTY (older Windows)**

1. Download [PuTTYgen](https://www.puttygen.com/)
2. Open PuTTYgen
3. Click "Generate" and move your mouse randomly
4. Click "Save private key" — save as `my-key.ppk`
5. Copy the text in "Public key for pasting" — this is your public key
6. Add this public key to your cloud provider (steps above)

To connect:
1. Open PuTTY
2. In "Host Name", enter: `<USERNAME>@your-server-ip` (username is 'openclaw' or 'hermes' depending on framework)
3. Go to Connection → SSH → Auth
4. Browse to your `.ppk` file
5. Click "Open"

### Key Already Exists?

If you've used SSH before (for GitHub, GitLab, etc.), you might already have a key:

```bash
# Check for existing keys
ls ~/.ssh

# If you see id_ed25519.pub, you're good
cat ~/.ssh/id_ed25519.pub
```

Use this existing key — no need to generate a new one.

## Connecting to Your Server

When Terraform finishes, it outputs your server IP:

```
server_ip = "123.45.67.89"
ssh_command = "ssh openclaw@123.45.67.89"  # or "ssh hermes@123.45.67.89"
```

**Connect (username is 'openclaw' or 'hermes' based on framework):**

```bash
ssh <USERNAME>@123.45.67.89
```

**First time?** You'll see:

```
The authenticity of host '123.45.67.89' can't be established.
ED25519 key fingerprint is SHA256:xxxxx...
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Type `yes` and press Enter. This happens once per server.

**Successful connection looks like:**

```
Welcome to Ubuntu 24.04 LTS
openclaw@openclaw-gateway:~$
```

You're now on the server! The prompt shows `username@hostname`.

## Common Commands

Once connected, here are useful commands:

```bash
# Check if OpenClaw is running
systemctl status openclaw-gateway

# View logs in real-time
journalctl -u openclaw-gateway -f

# Check Tailscale status (if using Tailscale)
sudo tailscale status

# Check disk space
df -h

# Check memory
free -h

# Exit the server
exit
```

## Troubleshooting

### "Permission denied (publickey)"

**Cause:** Your public key isn't on the server, or you're using the wrong username.

**Fix:**
1. Check your public key is added to the cloud provider
2. Make sure you're using `openclaw` as the username (not your personal username)
3. If your key is in a non-standard location: `ssh -i ~/.ssh/my-key openclaw@server-ip`

### "Connection timed out"

**Cause:** Server isn't running, or firewall is blocking you.

**Fix:**
1. Check the server is running in your cloud console
2. Wait 2-3 minutes after deployment (cloud-init takes time)
3. Check your IP is in `ssh_allowed_ips` (or use `["0.0.0.0/0"]` for any IP)

### "Host key verification failed"

**Cause:** You've connected to this IP before, but the server was replaced.

**Fix:**
```bash
ssh-keygen -R 123.45.67.89
ssh openclaw@123.45.67.89
```

### "No such file or directory" for key

**Cause:** Your key is in a different location.

**Fix:**
```bash
# Find your key
find ~ -name "id_ed25519*" 2>/dev/null

# Use the correct path
ssh -i /path/to/your/key openclaw@server-ip
```

## Security Best Practices

| Practice | Why |
|----------|-----|
| Never share your private key | It's your identity. Anyone with it can access your servers. |
| Don't email your private key | Email isn't secure. |
| Use different keys for different purposes | If one is compromised, others remain safe. |
| Use a passphrase (optional) | Extra layer of protection if someone gets your key file. |
| Disable password login | Passwords can be guessed. Keys can't. |

## What if I Lose My Key?

If you lose your private key, you can't SSH in. Your options:

1. **Use the cloud console** — Most providers have a "Console" or "VNC" option in the web interface. This gives you direct access.

2. **Add a new key** — Through the cloud console, you can add a new SSH key.

3. **Recreate the server** — Use `terraform destroy` and `terraform apply` again. Data will be lost.

## Need Help?

- Check the server logs: `journalctl -u openclaw-gateway -n50`
- Check cloud-init logs: `tail -f /var/log/cloud-init-output.log`
- See [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) for more common issues

## Quick Reference

```bash
# Generate a new key
ssh-keygen -t ed25519 -C "your-email@example.com"

# View your public key
cat ~/.ssh/id_ed25519.pub

# Connect to server
ssh openclaw@server-ip

# Use a specific key file
ssh -i ~/.ssh/my-key openclaw@server-ip

# Remove a server from known hosts
ssh-keygen -R server-ip

# Copy files to server
scp myfile.txt openclaw@server-ip:/home/openclaw/

# Copy files from server
scp openclaw@server-ip:/home/openclaw/file.txt ./
```