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:

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:

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
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
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:

# 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
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:

# 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):

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:

# 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:

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:

# 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 for more common issues

Quick Reference

# 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 ./