Skip to main content

​
vers connect

Connect to a running VM via SSH for interactive access.

​
Synopsis

vers connect                         # Connect to current HEAD VM
vers connect <vm-id|alias>          # Connect to specific VM
vers connect --host custom.host.com # Override connection host

​
Description

The connect command opens an SSH session to a running VM, giving you full interactive access to the VM’s terminal. The command automatically handles SSH key management and secure connection routing.

​
Basic Usage

​
Connect to Current HEAD VM

vers connect
Connects to whatever VM your HEAD is currently pointing to.

​
Connect to Specific VM

vers connect vm-abc123
vers connect my-app-vm
Connects directly to the specified VM by ID or alias.

​
How Connections Work

Vers uses SSH-over-TLS for secure connections:
  1. TLS Connection: Establishes encrypted TLS connection to {vm-id}.vm.vers.sh on port 443
  2. SSH Handshake: Performs SSH authentication over the TLS tunnel
  3. Interactive Session: Opens a full PTY terminal session
This approach:
  • Uses standard HTTPS port (443) - no firewall issues
  • Provides double encryption (TLS + SSH)
  • Automatically handles routing to your VM

​
SSH Key Management

The CLI automatically handles SSH authentication:
  1. Key Retrieval: Fetches your VM’s SSH private key from the Vers API
  2. Local Caching: Stores keys at /tmp/vers-ssh-keys/{vm-id}.key with secure permissions (0600)
  3. Automatic Auth: Uses the key for public key authentication as root user
You don’t need to manually manage SSH keys - everything is handled automatically.

​
What You’ll See

​
Successful Connection

vers connect my-app
Using current HEAD VM: vm-abc123
Fetching VM information...
Connecting to VM my-app...

root@vm-abc123:~#
You’re now connected as root with full access to the VM.

​
Requirements

​
VM Must Be Running

vers connect vm-paused123
Fetching VM information...
# Error: VM is not running (current state: Paused)
Solution: Resume the VM with vers resume or check its status with vers status.

​
Examples

​
Basic Development Workflow

# Check what VM you're on
vers checkout
Current HEAD: my-dev-env (State: Running)

# Connect to it
vers connect

root@vm-abc123:~# npm install
root@vm-abc123:~# npm start

​
Working with Multiple VMs

# Terminal 1: Connect to main environment
vers connect main-vm
root@main:~# python app.py

# Terminal 2: Connect to test environment
vers connect test-vm
root@test:~# python test_suite.py

​
Custom Host Override

# Connect via specific host (useful for custom setups)
vers connect my-vm --host custom.internal.host

​
SSH Session Features

​
Full Interactive Access

Once connected, you have complete root access to the VM: 
root@vm-abc123:~# ls
app.py  requirements.txt  src/

root@vm-abc123:~# vim app.py
root@vm-abc123:~# python app.py
root@vm-abc123:~# apt install nodejs npm

​
Terminal Support

  • Full PTY (pseudo-terminal) support
  • Terminal resize handling - window resizes are reflected in the VM
  • Color and formatting support (xterm-256color)

​
Multiple Sessions

You can open multiple SSH sessions to the same VM: 
# Terminal 1
vers connect my-vm
root@vm-abc123:~# python app.py

# Terminal 2 (different terminal window)
vers connect my-vm
root@vm-abc123:~# tail -f logs/app.log

​
Persistent State

VMs maintain their state between connections:
  • Running processes continue when you disconnect
  • Files and changes are preserved
  • Environment variables and configurations persist

​
Connection Keep-Alive

The SSH connection uses automatic keep-alive to maintain stable connections:
  • Sends keep-alive every 10 seconds
  • Tolerates up to 6 missed responses before disconnecting
  • Helps maintain connections over unreliable networks

​
Exiting the Session

To disconnect from the VM: 
root@vm-abc123:~# exit
# Returns to your host terminal
Or use Ctrl+D to exit the SSH session. The VM continues running.

​
Flags

​
--host

Override the connection host for custom network configurations: 
vers connect my-vm --host custom-server.example.com
This is useful for:
  • Custom network routing
  • Internal network configurations
  • Testing different connection paths

​
Error Scenarios

​
VM Not Found

vers connect nonexistent-vm
# Error: failed to get VM information: VM not found
Solution: Check available VMs with vers status or verify the VM ID/alias.

​
VM Not Running

vers connect stopped-vm
# Error: VM is not running (current state: Paused)
Solution: Resume the VM with vers resume.

​
SSH Key Issues

vers connect my-vm
# Error: failed to get or create SSH key: ...
Solution: Check your authentication status with vers login and ensure you have proper access.

​
Connection Timeout

vers connect my-vm
# Error: context deadline exceeded
Solution: Check your network connection. The VM may also still be starting up.

​
Connection Security

Vers SSH connections are secure:
  • SSH-over-TLS: All traffic encrypted twice (TLS layer + SSH layer)
  • Port 443: Uses standard HTTPS port, works through most firewalls
  • Public key authentication: No passwords - keys are managed automatically
  • Per-VM keys: Each VM has its own unique SSH key
  • Secure key storage: Keys stored with 0600 permissions (owner read/write only)

​
Tips

  • VMs continue running when you disconnect - your work is preserved
  • You can connect to the same VM from multiple terminals simultaneously
  • Use vers status to check VM states before connecting
  • SSH keys are automatically managed - no manual setup required
  • Use vers execute for single commands without an interactive session

​
See Also