SSH connection setup

Generate and configure SSH keys for secure GPU instance access.

What are SSH keys?

SSH keys are cryptographic key pairs used for secure authentication:

Public key: Uploaded to Spheron AI
Private key: Kept secure on your machine and never shared

SSH keys provide stronger security than passwords and enable automatic authentication.

Prerequisites

Terminal access (Linux, macOS, or Windows)
Spheron AI account
Basic terminal familiarity

Generate SSH key

Run ssh-keygen

Linux/Mac:

ssh-keygen -t ed25519 -C "your_email@example.com"

Windows PowerShell:

ssh-keygen -t ed25519 -C "your_email@example.com"

SSH Key Generation

Configure key

Save location: Press Enter for the default (~/.ssh/id_ed25519)
Passphrase: Press Enter twice for no passphrase, or set a passphrase for extra security

SSH Passphrase

Verify creation

The output confirms where both keys were saved:

Your identification has been saved in /Users/yourname/.ssh/id_ed25519
Your public key has been saved in /Users/yourname/.ssh/id_ed25519.pub

Private key: id_ed25519: never share this file
Public key: id_ed25519.pub: upload this to Spheron

Upload to Spheron AI

Method 1: Account settings (recommended)

Use this method to reuse keys across multiple deployments.

Navigate to settings

app.spheron.ai → Settings → SSH Keys

SSH Keys Settings

Add key

Click + Add SSH Key
Enter a key name
Paste your public key content:

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

Click Add Key

Method 2: During deployment

Upload a key when deploying an instance:

Select Upload New SSH Key
Choose a file or paste the public key content
Enter a key name
Continue deployment

Connect to instance

ssh root@<your-instance-ip>
 
# Specify key explicitly
ssh -i ~/.ssh/id_ed25519 root@<your-instance-ip>

Best practices

Only upload public keys (.pub files)
Never share private keys
Use passphrases for additional security
Rotate keys every 90 days
Use different keys for different services
Back up private keys securely
Delete unused keys

See Security Best Practices for comprehensive guidance.

Troubleshooting

Permission denied:

# Check key is loaded
ssh-add -l
 
# Add key to agent
ssh-add ~/.ssh/id_ed25519
 
# Verify permissions
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Wrong key:

Verify the correct public key was uploaded
Check the key fingerprint matches
Try with an explicit key: ssh -i ~/.ssh/id_ed25519 user@<your-instance-ip>

Connection timeout:

Verify the instance is running
Check the IP address is correct
Ensure the firewall allows SSH (port 22)

What's next

Getting Started: Complete setup guide
User Settings: Manage SSH keys
Security Best Practices: Security guidelines
Quick Start: Fast deployment walkthrough