# Key pairs

Source: https://docs.quake.ai/docs/compute/concepts/key-pairs
Markdown: https://docs.quake.ai/docs/compute/concepts/key-pairs.md

---

# Key pairs

Key pairs are the default way you prove you are allowed to log in to Linux instances without sending a password over the network. Quake AI stores the **public** half and injects it into the guest; you keep the **private** half on your workstation or in a secure vault. If someone else gets the private key, they can authenticate as you, so key hygiene is central to cloud security.

## What a key pair is

A key pair is two mathematically related keys used in public-key cryptography.

The **public key** can be distributed widely. It is placed on the instance (for SSH, typically in `authorized_keys` for the default cloud user). It identifies which private key must have signed or decrypted a given operation.

The **private key** stays only with you (or your secret store). You use it with SSH or, on Windows images, sometimes with RDP-related setups, depending on image configuration. The private key never needs to travel to the instance on each login; SSH proves possession of the private key without transmitting it.

## How key pairs connect to instances

<Figure size="md" caption="SSH key pair flow: the public half is uploaded and injected via cloud-init while the private half never leaves your workstation">

```mermaid
sequenceDiagram
    accTitle: SSH key pair flow on Quake AI
    accDescr: User generates a key locally, uploads the public half, the platform injects it via cloud-init, and SSH proves possession of the private half on first login

    participant User as You (workstation)
    participant Platform as Quake AI
    participant Instance as New instance

    User->>User: ssh-keygen
    User->>Platform: Upload public key
    Note right of User: Private key stays local
    User->>Platform: Launch instance with key
    Platform->>Instance: Inject public key via cloud-init
    User->>Instance: SSH (proves private key)
    Instance-->>User: Session established
```

</Figure>

When you create an instance and select a key pair, Compute records the association and places the public key on the guest during provisioning, via cloud-init, so the first boot already trusts your key.

To connect, your SSH client presents credentials derived from the private key. The instance checks them against the stored public key and grants a session if they match. Password authentication, when enabled at all, is a separate path; key-based login avoids password guessing and interception on the wire.

You can generate new key pairs in the Console or CLI, download the private key once, and store it in a secure location. You can instead **import** a public key you already use elsewhere so the same key works across environments.

Multiple key pairs per project let you separate people, automation, and environments. Listing, inspecting, and deleting keys is available through the same management surfaces as the rest of Compute.

## Security and automation

They reduce reliance on shared passwords and make automation safer: CI systems can use dedicated keys with narrow scope. Combined with security groups, you get defense in depth: network policy at the edge and cryptographic proof at login.

Encryption workflows also use public keys to protect data in transit to a known recipient; the operational pattern is the same idea with different tooling.

## Automation and operational use

CI/CD systems and configuration management often use dedicated key pairs scoped to a single pipeline or environment. That separation limits blast radius if a runner is compromised and makes audits easier: you know which automation owns which key. When you rotate, update the public key everywhere it was injected; long-running instances may need a Console session or configuration management pass if they were launched before the rotation.

Some organizations pair key-based access with bastion hosts or VPN entry so SSH is never exposed on the public internet, even when a floating IP exists.

## Practices that reduce risk

Back up private keys in an encrypted store; losing a key can mean rebuilding access paths. Rotate keys on a schedule or after personnel changes. Share private keys only with people or systems that need them, and revoke by replacing keys on instances when a key might be exposed.

Prefer passphrases on private keys where your tooling supports it, and use agent forwarding only when you understand the trade-offs: forwarding can expose your agent to remote hosts.

## Further reading

**On this platform:**

- [Add an SSH key pair to your account](/docs/tools/add-ssh-key): generate or import a key pair
- [Instances](/docs/compute/concepts/instances): how key pairs connect to instance provisioning
- [Key pairs console](/reference/compute/console/key-pairs): Console reference for key pair management
- [Key pair CLI reference](/reference/compute/key-pairs-cli): `openstack keypair` commands

**External resources:**

- [OpenSSH manual](https://man.openbsd.org/ssh): authoritative reference for the SSH protocol and client configuration
- [ssh-keygen manual](https://man.openbsd.org/ssh-keygen): key generation options including ED25519 and ECDSA algorithms