# SSH

> Install your public key on a machine and connect through VMYard's SSH gateway.

Install one OpenSSH public key on a machine and VMYard gives it a port on an SSH gateway. Connect with any SSH client.

> [!NOTE]
> In the console, a machine's **Network** tab installs a key and copies the `ssh` command. From a terminal, `vy ssh <machine>` installs your key if needed and runs `ssh`; the SDKs have `setSshKey` (`set_ssh_key` in Python); or use the HTTP API below, then your own `ssh`. SSH needs a deployment with an edge configured (otherwise `503 ingress_unavailable`) and an image that runs an SSH server. Machines on the `docker` development backend can't use SSH.

## Install a key

```sh
curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"
```

`public_key` is one line in OpenSSH format, `TYPE BASE64 [COMMENT]`, with no trailing newline, at most 8 KiB:

- `ssh-ed25519`
- `ecdsa-sha2-nistp256`, `ecdsa-sha2-nistp384`, or `ecdsa-sha2-nistp521`
- `ssh-rsa` of at least 3072 bits

Installing is an [operation](/docs/concepts/operations) and needs a running machine. Installing another key replaces the first and keeps the same gateway port. VMYard records the key's type and `SHA256:` fingerprint, never the key itself.

## Connect

Once the operation succeeds, the machine's `ssh` field says where to connect:

```sh
curl "$VMYARD_API_URL/v1/machines/$MACHINE_ID" -H "Authorization: Bearer $VMYARD_API_KEY" | jq .ssh
```

```json
{ "host": "ssh.eu.example.com", "port": 2201, "user": "vmyard" }
```

```sh
ssh -p 2201 vmyard@ssh.eu.example.com
```

The gateway only forwards your connection to port 22 in the machine; the machine's own SSH server checks your key. The login user is `vmyard` when the image has that user, otherwise `root`; use the `user` the API reports. `host` is `null` when the deployment has no gateway configured for the machine's host or region.

## Remove the key

```sh
curl -X DELETE "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Removing the key releases the gateway port, and `ssh` becomes `null`.

## Host keys

Host keys come from the machine's image and disk. They stay the same across a stop and start of the same machine.

## Access

Installing and removing keys needs Owner, Admin, or Operator access, or an API key with at least the `use_existing` preset. An invalid key is refused with `422` before anything changes.