Skip to main content
Add your public SSH key to a sandbox. Then use ssh, scp, sftp, and port forwarding with your normal tools. With the CLI, vms ssh <name> adds your key and the host key in one step. See CLI reference.

Add my SSH key to a sandbox and connect to it.

Before you start

  • You need an API key with the sandboxes:ssh scope. See API keys.
  • You need an SSH key pair. To make one, run ssh-keygen -t ed25519.
  • ssh.vms.dev works on IPv4 and on IPv6 networks.

Add your key to the sandbox

Send POST /v1/sandboxes/{id}/ssh-keys with your public key in publicKey. The comment of the key becomes its name, unless you send a name.
The answer is the key, with the status 201:
  • A running sandbox gets the key in a few seconds. A stopped sandbox gets it when it starts.
  • A sandbox can have 20 keys. The key types are ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521, and ssh-rsa with 2048 bits or more.
  • To add or delete many keys in one request, send POST /v1/sandboxes/{id}/ssh-keys/create-many with items, or POST /v1/sandboxes/{id}/ssh-keys/delete-many with ids.
  • The keys of the sandbox replace the content of /home/user/.ssh/authorized_keys each time the keys change. A key that you write in that file yourself goes away. The key with the comment vms-ssh-proxy lets ssh.vms.dev connect. Do not remove it.

Open a shell

Connect to ssh.vms.dev with the sshUser of the sandbox as the user name. GET /v1/sandboxes/{id} gives it. It is the name of the sandbox and the code of your workspace, such as agent-42-k3m7q2v9. A sandbox with no name has its ID as its sshUser.
The shell opens as user in /home/user. user can use sudo without a password. These also work: The name alone, such as ssh agent-42@ssh.vms.dev, also works while only one sandbox with that name has your key. A sandbox in another workspace can have the same name and a copy of your public key. Then the name alone does not connect, and the sshUser or the sandbox ID does.

Check the host keys

ssh.vms.dev has one host key for all sandboxes. To skip the first prompt, add this line to ~/.ssh/known_hosts:
Its fingerprint is SHA256:tX7dGz8vfwouK34gkeRCxyyKdlkiA3JkGN9Eey8Qc2Y. Each sandbox also has a host key of its own. GET /v1/sandboxes/{id} shows it in sshHostKey. The field is null until the sandbox uses the key, a few seconds after it is running. The sandbox keeps the key until you delete it.
You see this key when you connect to the sandbox itself, not to ssh.vms.dev:
  • At the IPv6 address of the sandbox. Port 22 is open to the internet. Add <ipv6> <sshHostKey> to ~/.ssh/known_hosts, then run ssh user@2604:2dc0:100:32d5::1:1a.
  • Through ssh.vms.dev as a jump host. Add agent-42 <sshHostKey> to ~/.ssh/known_hosts, then run ssh -J agent-42@ssh.vms.dev -o HostKeyAlias=agent-42 user@localhost.

Delete a key

Send DELETE /v1/sandboxes/{id}/ssh-keys/{keyId}. New connections with the key fail. List the keys with GET /v1/sandboxes/{id}/ssh-keys.

Errors

OpenSSH 10.1 and later can show a warning that the connection to ssh.vms.dev does not use a post-quantum key exchange.