> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to a sandbox with SSH

> Add your SSH key to a sandbox, then open a shell with ssh <sshUser>@ssh.vms.dev or at the IPv6 address of the sandbox.

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](https://vms.dev/docs/reference/cli.md#ssh).

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

Use POST /v1/sandboxes/{id}/ssh-keys with the content of my public key file, such as \~/.ssh/id\_ed25519.pub, in publicKey.
Then connect with ssh [USER@ssh.vms.dev](mailto:USER@ssh.vms.dev), where USER is the sshUser of the sandbox from GET /v1/sandboxes/{id}.
Do not ask me to share my API key or my private key.

## Before you start

* You need an API key with the `sandboxes:ssh` scope. See [API keys](https://vms.dev/docs/workspace/api-keys.md).
* 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`.

```typescript TypeScript theme={null}
import { readFile } from "node:fs/promises";
import { homedir } from "node:os";

const publicKey = await readFile(`${homedir()}/.ssh/id_ed25519.pub`, "utf8");

const response = await fetch(
  `https://vms.dev/api/v1/sandboxes/${sandboxId}/ssh-keys`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VMS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ publicKey }),
  },
);

const key = await response.json();
```

```bash cURL theme={null}
curl -X POST "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/ssh-keys" \
  -H "Authorization: Bearer $VMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publicKey\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
```

The answer is the key, with the status `201`:

```json theme={null}
{
  "id": "ssk_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "sandboxId": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "name": "dev@example.com",
  "publicKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAINiCC4DtKiK4pnatEMwz9fpZks348+f9WnodyRCkr/al",
  "fingerprint": "SHA256:DbPhl9dNAPM0TB3+SLh/OdwIJ9Rtl3hGJU6s/NJyjOg",
  "createdAt": "2026-11-16T03:30:00.000Z"
}
```

* 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`.

```bash theme={null}
ssh agent-42-k3m7q2v9@ssh.vms.dev
```

The shell opens as `user` in `/home/user`. `user` can use `sudo` without a password.

These also work:

| Task | Command |
| - | - |
| Run one command | `ssh agent-42-k3m7q2v9@ssh.vms.dev 'npm test'` |
| Copy a file into the sandbox | `scp app.tar.gz agent-42-k3m7q2v9@ssh.vms.dev:` |
| Open SFTP | `sftp agent-42-k3m7q2v9@ssh.vms.dev` |
| Open port 3000 of the sandbox on your computer | `ssh -N -L 3000:localhost:3000 agent-42-k3m7q2v9@ssh.vms.dev` |

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`:

```text theme={null}
ssh.vms.dev ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIHcLSnnRFPMmTzk9xK6Y0JSskrpPNJzsBEv85aIxfEcc
```

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.

```json theme={null}
{
  "id": "sbx_06d8k3m7q2v9x4b1n5c0e8f2ja",
  "name": "agent-42",
  "state": "running",
  "ipv6": "2604:2dc0:100:32d5::1:1a",
  "sshHostKey": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBxeBscOLFNYc51J/07enC+NzoRMy+kD3+N+RrStzLQU"
}
```

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

```bash theme={null}
curl -X DELETE "https://vms.dev/api/v1/sandboxes/sbx_06d8k3m7q2v9x4b1n5c0e8f2ja/ssh-keys/ssk_06d8k3m7q2v9x4b1n5c0e8f2ja" \
  -H "Authorization: Bearer $VMS_API_KEY"
```

## Errors

| Status or message | Meaning |
| - | - |
| `400 invalid` | The key is not an OpenSSH public key, or its type is not in the list above. |
| `403 forbidden` | The API key does not have the `sandboxes:ssh` scope. |
| `404 not_found` | The workspace has no sandbox with this ID, or the sandbox has no key with this ID. |
| `409 conflict` | The key is already on the sandbox, or the sandbox has 20 keys. |
| `Permission denied (publickey)` | No sandbox with this name or ID has your key. |
| `Could not resolve hostname ssh.vms.dev` or `Could not connect to ssh.vms.dev. Check your network.` | Your computer cannot reach `ssh.vms.dev`. Check your network, your DNS, and your firewall for TCP port 22. |
| `The sandbox is not running.` | Start the sandbox, then connect again. |
| `The sandbox is starting.` | Connect again when the sandbox is `running`. |

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

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.