Skip to main content

​
Synopsis

smolvm ssh <vm_id> [OPTIONS]

​
Description

The ssh command opens an interactive SSH session to an existing VM. If the VM is stopped or newly created, SmolVM automatically starts it and waits for SSH readiness before connecting.

​
Arguments

​
vm_id
string
required
The identifier of the VM to connect to. This is the name you provided when creating the VM with smolvm create.

​
Options

​
--ssh-key
string
default:"~/.smolvm/keys/id_ed25519"
SSH private key path for authentication.
​
--ssh-user
string
default:"root"
SSH user to connect as.
​
--boot-timeout
float
default:"30"
Seconds to wait for VM boot and SSH readiness if the VM needs to be started.

​
Examples

​
Connect to a running VM

smolvm ssh my-agent

​
Connect with a custom SSH key

smolvm ssh my-agent --ssh-key ~/.ssh/custom_key

​
Connect as a different user

smolvm ssh my-agent --ssh-user ubuntu

​
Allow more time for boot

If a VM is stopped and needs to restart, increase the timeout: 
smolvm ssh my-agent --boot-timeout 60

​
Auto-start behavior

The ssh command handles VMs in different states:
VM stateBehavior
RunningConnects immediately
CreatedStarts the VM, waits for SSH readiness, connects
StoppedStarts the VM, waits for SSH readiness, connects
ErrorPrints an error and exits (recreate the VM)

​
Exit codes

CodeDescription
0SSH session ended normally
1Error - connection failed, VM in error state, or SSH binary not found
If you get an “ssh binary not found” error, install the openssh-client package on your system.
Last modified on March 29, 2026