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 connection routing based on whether you’re connecting locally or remotely.

​
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.

​
Connection Process

  1. VM Information: Fetches VM details and connection information (30-second timeout)
  2. State Check: Verifies the VM is in “Running” state
  3. SSH Key Management: Automatically retrieves or creates SSH keys for the VM
  4. Connection Routing: Determines local vs remote connection method
  5. SSH Session: Establishes secure SSH connection with proper authentication

​
Connection Methods

​
Local Connections

When connecting to a local Vers instance:
  • Host: Direct VM IP address
  • Port: 22 (standard SSH)
  • Example: 192.168.1.100:22

​
Remote Connections

When connecting to a remote Vers instance:
  • Host: Vers server hostname
  • Port: VM’s assigned SSH port (DNAT’d)
  • Example: api.vers.sh:32768
The CLI automatically detects which method to use based on your Vers server configuration.

​
What You’ll See

​
Successful Connection

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

root@vm-abc123:~#

​
Remote Connection

vers connect
Using current HEAD VM: vm-def456
Fetching VM information...
Connecting to VM vm-def456...
Connecting to api.vers.sh on port 32768

root@vm-def456:~#

​
SSH Key Management

The CLI automatically handles SSH authentication:
  • Key Creation: Creates SSH keys if they don’t exist
  • Key Storage: Stores keys securely for reuse
  • Authentication: Uses public key authentication only
  • Security: Disables host key checking for VM connections
You don’t need to manually manage SSH keys or configure authentication.

​
Requirements

​
VM Must Be Running

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

​
SSH Port Available

vers connect vm-no-ssh
Fetching VM information...
# Error: VM does not have SSH port information available
Solution: The VM may still be starting up. Wait a moment and try again.

​
Examples

​
Basic Development Workflow

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

# Connect to it
vers connect
Using current HEAD VM: vm-abc123
Connecting to VM my-dev-env...
Connecting to 192.168.1.100 on port 22

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 complex network setups)
vers connect my-vm --host custom.internal.host
Fetching VM information...
Connecting to custom.internal.host on port 32768

​
SSH Session Features

​
Full Interactive Access

Once connected, you have complete 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

​
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

​
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 10.0.1.100
vers connect my-vm --host my-custom-vers-server.com
This is useful for:
  • Custom network routing
  • Internal network configurations
  • Testing different connection paths

​
Error Scenarios

​
VM Not Found

vers connect nonexistent-vm
Fetching VM information...
# 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
Fetching VM information...
# Error: VM is not running (current state: Paused)
Solution: Check VM status and resume if needed.

​
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
Fetching VM information...
# Error: failed to get VM information: context deadline exceeded
Solution: VM information fetching has a 30-second timeout. Check your network connection.

​
SSH Connection Failed

vers connect my-vm
Connecting to 192.168.1.100 on port 22
# Error: failed to run SSH command: connection refused
Solution: The VM may still be starting up. Wait a moment and try again.

​
Connection Security

The CLI uses secure SSH practices:
  • Public key authentication only: No password authentication
  • Automatic key management: Keys are created and managed securely
  • Host key verification disabled: For VM connections (VMs are ephemeral)
  • Dedicated identity files: Each VM gets its own SSH key

​
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
  • Connection method (local vs remote) is automatically detected
  • SSH keys are automatically managed - no manual setup required

​
See Also