> ## Documentation Index > Fetch the complete documentation index at: https://docs.vers.sh/llms.txt > Use this file to discover all available pages before exploring further. # Connect # vers connect Connect to a running VM via SSH for interactive access. ## Synopsis ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers connect # Connect to current HEAD VM vers connect # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers connect ``` Connects to whatever VM your HEAD is currently pointing to. ### Connect to Specific VM ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers connect stopped-vm # Error: VM is not running (current state: Paused) ``` **Solution**: Resume the VM with `vers resume`. ### SSH Key Issues ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 ## Common Patterns ### Open a shell on HEAD ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers connect ``` ### Connect by alias ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} vers connect my-dev-vm ``` ### Run a one-off interactively vs non-interactively If you just want to run a command and get the output, `vers execute` is usually a better fit. Use `vers connect` when you need a TTY (e.g. `vim`, `top`, `less`, `psql`). ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} # Non-interactive vers execute my-vm -- uptime # Interactive (TTY needed) vers connect my-vm # then: top ``` ## See Also * [vers status](status) - Check VM states and availability * [vers execute](execute) - Run single commands without interactive session * [vers copy](copy) - Transfer files to/from VMs * [vers checkout](checkout) - Switch between VMs * [vers pause](pause) / [vers resume](resume) - Control VM states