AgentOSAgentOS

SSH Access

Connect to your AgentOS Cloud VM via SSH for terminal access.

SSH gives you direct terminal access to your AgentOS Cloud VM. Use it for setup, troubleshooting, or when you prefer working in your local terminal.

Quick Connect

Copy the SSH command from your dashboard:

ssh dev@{your-subdomain}.vm.runagentos.com

Replace {your-subdomain} with your actual machine ID (shown in your dashboard).

First-Time Setup

1. Add Your SSH Key

Before you can connect, add your public key to AgentOS Cloud:

Find your existing key:

# macOS/Linux
cat ~/.ssh/id_ed25519.pub

# Windows PowerShell
Get-Content ~/.ssh/id_ed25519.pub

Or generate a new one:

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

2. Add to Dashboard

  1. Go to your dashboard
  2. Find the SSH Keys panel
  3. Click Add
  4. Paste your public key
  5. Give it a name (e.g., "MacBook", "Work Laptop")

3. Launch Your VM

After adding your key and subscribing, click Launch environment. Your key is automatically injected during provisioning.

SSH Configuration

For convenience, add this to ~/.ssh/config:

Host agentos
    HostName {your-subdomain}.vm.runagentos.com
    User dev
    IdentityFile ~/.ssh/id_ed25519

Then connect with just:

ssh agentos

Port Forwarding

Access services running on your VM locally:

Forward a Single Port

# Forward VM port 3000 to localhost:3000
ssh -L 3000:localhost:3000 dev@{subdomain}.vm.runagentos.com

Multiple Ports

ssh -L 3000:localhost:3000 -L 5432:localhost:5432 dev@{subdomain}.vm.runagentos.com

Common Use Cases

ServiceCommand
Dev server-L 3000:localhost:3000
PostgreSQL-L 5432:localhost:5432
Redis-L 6379:localhost:6379
Vite HMR-L 5173:localhost:5173

IDE Integration

VS Code Remote SSH

  1. Install the Remote - SSH extension
  2. Open Command Palette → "Remote-SSH: Connect to Host"
  3. Enter: dev@{subdomain}.vm.runagentos.com
  4. VS Code opens with full remote editing capabilities

Cursor

  1. Use the built-in remote SSH feature
  2. Connect to dev@{subdomain}.vm.runagentos.com
  3. Open your project folder

JetBrains Gateway

  1. Open JetBrains Gateway
  2. Choose "SSH Connection"
  3. Add your VM as a new target
  4. Select your IDE and project

File Transfer

Copy Files To VM

# Single file
scp local-file.txt dev@{subdomain}.vm.runagentos.com:~/projects/

# Directory
scp -r my-project/ dev@{subdomain}.vm.runagentos.com:~/projects/

Copy Files From VM

scp dev@{subdomain}.vm.runagentos.com:~/projects/output.txt ./

Using rsync

For larger transfers with resume support:

rsync -avz --progress my-project/ dev@{subdomain}.vm.runagentos.com:~/projects/my-project/

Multiple SSH Keys

You can add multiple SSH keys to your account—useful if you use different machines:

  1. Go to dashboard → SSH Keys
  2. Click Add for each key
  3. Name them descriptively (e.g., "MacBook Pro", "Work Desktop", "iPad")

All keys are injected when you provision a new VM.

Troubleshooting

Connection Refused

# Check if VM is running
# Dashboard should show "running" status

# Test connectivity
ssh -v dev@{subdomain}.vm.runagentos.com

The -v flag shows verbose output to help diagnose issues.

Permission Denied

  1. Verify your SSH key is added to the dashboard
  2. Check the fingerprint matches your local key: 
    ssh-keygen -lf ~/.ssh/id_ed25519.pub
  3. Ensure you're using the correct key: 
    ssh -i ~/.ssh/id_ed25519 dev@{subdomain}.vm.runagentos.com

Host Key Changed

If you destroy and re-provision your VM, the host key changes:

ssh-keygen -R {subdomain}.vm.runagentos.com

Then reconnect—you'll be prompted to accept the new key.

Slow Connection

Try enabling compression:

ssh -C dev@{subdomain}.vm.runagentos.com

Or add to your SSH config:

Host agentos
    Compression yes

Security Notes

  • SSH keys are injected at VM creation time
  • The dev user has sudo access
  • VMs are isolated per user
  • Traffic is encrypted end-to-end

Next Steps