# 1Password SSH & Git Documentation > SSH key management, Git commit signing, and SSH agent configuration with 1Password. This file contains all documentation content in a single document following the llmstxt.org standard. ## Advanced use cases ## Gradual migration ### Mac & Linux If you don't want to use the 1Password SSH agent for all your hosts right away, you don't have to. The 1Password SSH agent can run alongside another SSH agent, like the OpenSSH agent. The SSH client config file (`~/.ssh/config`) allows you to provide different authentication details for different hosts. So, you can try the 1Password SSH agent with one or two hosts to start, then gradually migrate the rest when you're ready. Here are a few examples of what your `~/.ssh/config` file could look like: **Example 1:** ```toml # A host that uses the 1Password agent Host raspberry-pi HostName 192.168.12.34 User pi IdentityAgent ~/.1password/agent.sock # A host that uses a local private key file that isn't saved in 1Password Host ec2-server HostName 54.123.45.67 User ec2-user IdentityFile ~/.ssh/ssh-key-not-on-1password.pem ``` **Example 2:** ```toml # By default, use the 1Password SSH agent for all hosts Host * IdentityAgent ~/.1password/agent.sock # A host that uses a local private key file that isn't saved in 1Password Host ec2-server HostName 54.123.45.67 User ec2-user IdentityFile ~/.ssh/ssh-key-not-on-1password.pem IdentityAgent none ``` **Example 3:** ```toml # By default, use a local private key file that's not saved in 1Password Host * IdentityFile ~/.ssh/ssh-key-not-on-1password.pem # Use the 1Password agent on a single host instead of the local key file Host raspberry-pi HostName 192.168.12.34 User pi IdentityAgent ~/.1password/agent.sock IdentityFile none ``` ### Windows No changes to the SSH configuration need to be made on Windows. Windows doesn't have the same flexibility with the `~/.ssh/config` file as macOS and Linux, because Microsoft OpenSSH listens to a fixed pipe `(\\.\pipe\openssh-ssh-agent)`. If you want to use the 1Password SSH agent on Windows, it will authenticate for all hosts. ## SSH server six-key limit :::tip Use [SSH bookmarks](/docs/ssh/bookmarks/) to match your SSH hosts with SSH keys and avoid server key limitations. ::: SSH agents work together with SSH clients by trying all public keys the agents manage, offering them one by one to SSH servers until the server acknowledges one that works. However, OpenSSH servers are configured by default to limit the amount of authentication attempts for an incoming SSH connection (`MaxAuthTries`) to six. If your SSH client offers the SSH server a seventh key, the server will refuse the connection and you'll see this error message in your SSH client: ```text Too many authentication failures ``` Server administrators *can* increase the limit by setting `MaxAuthTries` in the [server's `/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config), but in many cases you can't (or don't want to) change this. Instead, you can specify which host should be matched to which SSH key. ### Match key with host To avoid the `Too many authentication failures` error, your SSH client needs to know which SSH public key should be used with which host. This can be configured in the SSH config file by setting `IdentityFile` in a `Host` block to the public key you want use with that host. You can configure [SSH Bookmarks](/docs/ssh/bookmarks/) to automatically manage this for you. Alternatively, you can manually edit your SSH config file: 1. In your 1Password app, select the **Download** button on the "Public key" field of the SSH item. 2. In your `~/.ssh/config` file, add an entry for the host you're connecting to and set `IdentityFile` to the path of the **public key** you just downloaded. The private key can stay in 1Password. ```toml Host github.com IdentityFile ~/.ssh/public-key-downloaded-from-1password.pub IdentitiesOnly yes ``` Now your SSH clients will know which key to use when connecting to SSH servers, so you won't run into these authentication limits. :::warning[caution] Some SSH clients don't support specifying public keys in `IdentityFile`. See [SSH client compatibility](/docs/ssh/agent/compatibility/). ::: ### Create an SSH agent config file You can also create an optional [SSH agent config file](/docs/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`). The agent config file allows you to specify which keys the SSH agent can make available to SSH servers and the order it offers those keys to servers. You can use the SSH agent config file alongside your SSH client config file (`~/.ssh/config`) to help further avoid authentication limits. ## Use multiple Git identities on the same machine When you connect to remote Git repositories from your local machine, all connections that are authenticated over SSH use the same `git` user. If you want to use SSH with multiple Git identities on the same machine, such as a work and personal account, you'll need to: - Define SSH host aliases for the different Git identities in your SSH config file. - Configure which SSH keys are used to authenticate connections to the remote Git repositories. - Update the URLs for your Git remotes to use the new SSH host aliases. To get started, follow these steps: 1. In the 1Password app, locate the SSH Key item for one of your Git accounts. 2. Select the down arrow on the "public key" field and choose **Download**. _[Download your public key]_ 3. Save the public key to your `~/.ssh/` directory. 4. Repeat steps 1–3 for each SSH key you need to use. 5. On your local machine, edit your `~/.ssh/config` file to add SSH host sections for each Git identity. For example, to configure SSH hosts for your personal and work GitHub accounts, you would add the following to your SSH config file: ```text title="~/.ssh/config" # Personal GitHub Host personalgit HostName github.com User git IdentityFile ~/.ssh/personal_git.pub IdentitiesOnly yes # Work GitHub Host workgit HostName github.com User git IdentityFile ~/.ssh/work_git.pub IdentitiesOnly yes ``` You can adjust the host (the alias name) and hostname, if needed, and you'll need to set `IdentityFile` to use the public key you saved in your `~/.ssh/` directory for that repository. 6. For each Git repository, change the `git` URL to use one of the new SSH host aliases instead of the default host URL, such as `git@github.com`. ```bash git remote set-url origin :/.git ``` For example: ```bash git remote set-url origin personalgit:1password/1password-teams-open-source.git ``` Now your SSH clients will know which SSH key to use for each Git identity. Learn more about how to [sign Git commits with SSH](/docs/ssh/git-commit-signing/). --- ## SSH client compatibility The 1Password SSH agent has been tested for compatibility with a number of different clients that use SSH and Git. **Mac:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[Cyberduck](#cyberduck)** | SFTP | ✅ Yes | | **[DataGrip](#datagrip)** | SSH tunneling | ✅ Yes | | **[FileZilla](#filezilla)** | SFTP | ✅ Yes | | **[Fork](#fork)** | Git | ✅ Yes | | **[ForkLift](#forklift)** | SFTP | ✅ Yes | | **[git CLI](#git-cli)** | Git | ✅ Yes | | **[Gitfox](#gitfox)** | Git | ✅ Yes | | **[GitHub Desktop](#github-desktop)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **GitUp** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[Nova](#nova)** | Git | ✅ Yes | | **[OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Postico](#postico)** | SSH tunneling | ❌ No | | **[Sequel Ace](#sequel-ace)** | SSH tunneling | ❌ No | | **[Sourcetree](#sourcetree)** | Git | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[TablePlus](#tableplus)** | SSH tunneling | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Tower](#tower)** | Git | ✅ Yes | | **[Transmit](#transmit)** | SFTP | ✅ Yes | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | | **[Xcode](#xcode)** | Git | ❌ No | **Windows:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[Celestial Software](#celestial-software)** | SSH, SFTP | ✅ Yes | | **[Cyberduck](#cyberduck)** | SFTP | ✅ Yes | | **[FileZilla](#filezilla)** | SFTP | ❌ No | | **[Fork](#fork)** | Git | ✅ Yes | | **[Git for Windows](#git-for-windows)** | Git | ✅ Yes | | **[GitHub Desktop](#github-desktop)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[Microsoft OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Pageant](#pageant)** | SSH | ❌ No | | **[PuTTY](#putty)** | SSH | ❌ No | | **[Sourcetree](#sourcetree)** | Git | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Tower](#tower)** | Git | ✅ Yes | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | **Linux:** | Name | SSH Capability | Compatible with 1Password | | --- | --- | --- | | **[DataGrip](#datagrip)** | SSH tunneling | ✅ Yes | | **[git CLI](#git-cli)** | Git | ✅ Yes | | **[GitKraken](#gitkraken)** | Git | ✅ Yes | | **[JetBrains IDEs](#jetbrains-ide)** | Git | ✅ Yes | | **[OpenSSH](#openssh)** | SSH, SFTP | ✅ Yes | | **[Sublime Merge](#sublime-merge)** | Git | ✅ Yes | | **[Termius](#termius)** | SSH | ❌ No | | **[Visual Studio Code](#vs-code)** | Git | ✅ Yes | // Args children, icon, prefixText, // Flags noPrefix, // Templates authSock, identityAgent, identityFile, commitSigning, gitBinarySetting, jetbrainsSocketCaveat, macAppStore, windowsPipe, windowsPipeWithGitconfig, pageantOnly, anySSHAgent }) => { const text = () => { if (authSock) { return {prefixText} agent configuration with `SSH_AUTH_SOCK`.; } if (windowsPipe) { return {prefixText} using the agent over the OpenSSH pipe (`\\.\pipe\openssh-ssh-agent`).; } if (windowsPipeWithGitconfig) { return {prefixText} using the agent over the OpenSSH pipe with the `.gitconfig` file set up properly.; } if (identityAgent) { return {prefixText} agent configuration with `IdentityAgent`.; } if (identityFile) { return {prefixText} setting public keys as `IdentityFile`.; } if (commitSigning) { return {prefixText} signing Git commits with SSH keys.; } if (gitBinarySetting) { return You may need to switch the Git binary in the preferences.; } if (jetbrainsSocketCaveat) { return If you're seeing errors around the socket path, go to `Advanced Settings` > `SSH` and set `Configuration files parser` to `OpenSSH`.; } if (macAppStore) { return {prefixText} the Mac App Store version.; } if (pageantOnly) { return No support for SSH agents over the OpenSSH pipe, only works with Pageant.; } if (anySSHAgent) { return {prefixText} any SSH agent. Uses a built-in key management system.; } if (noPrefix) { return {children}; } return {prefixText} {children}; } return ( {icon} {text.apply()} ) }; return } prefixText="Support for" {...props} /> }; return } prefixText="No support for" {...props} /> }; return } prefixText="" {...props} /> }; return } prefixText="" {...props} /> }; // This should not be displayed to customers // return return }; --- ## Working with SSH clients ### Agent configuration with `IdentityAgent` {#identity-agent} On Mac and Linux, most SSH and Git clients check your `~/.ssh/config` file for the `IdentityAgent` setting for the corresponding host. The clients then use the configured agent socket path to handle SSH authentication. This option gives you the most flexibility, like the ability to configure [multiple agents side by side](/docs/ssh/agent/advanced#gradual-migration). However, not every SSH client adheres to every value in the SSH config file. In the list below, you can see whether or not your SSH client supports configuration with `IdentityAgent`. ### Agent configuration with `SSH_AUTH_SOCK` {#ssh-auth-sock} On Mac and Linux, you can also configure the agent socket path using the `SSH_AUTH_SOCK` environment variable. There are more SSH clients that support `SSH_AUTH_SOCK` than `IdentityAgent`. For clients that support both, `IdentityAgent` usually takes precedence over `SSH_AUTH_SOCK`. Follow the steps for your operating system to configure `SSH_AUTH_SOCK` for your SSH client: **Mac:** #### Configure `SSH_AUTH_SOCK` for the terminal To configure `SSH_AUTH_SOCK` for the terminal, run: ``` export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ``` Any command you run within that same shell will use the 1Password SSH agent. To pass `SSH_AUTH_SOCK` to a GUI application, you can use the `open` command to launch the application: ```shell export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock open -a /Applications/.app ``` #### Configure `SSH_AUTH_SOCK` globally for every client If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a launch agent: ```shell mkdir -p ~/Library/LaunchAgents cat << EOF > ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist Label com.1password.SSH_AUTH_SOCK ProgramArguments /bin/sh -c /bin/ln -sf $HOME/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock \$SSH_AUTH_SOCK RunAtLoad EOF launchctl load -w ~/Library/LaunchAgents/com.1password.SSH_AUTH_SOCK.plist ``` **Linux:** #### Configure `SSH_AUTH_SOCK` for the terminal To configure `SSH_AUTH_SOCK` for the terminal, run: ``` export SSH_AUTH_SOCK=~/.1password/agent.sock ``` Any command you run within that same shell will use the 1Password SSH agent. #### Configure `SSH_AUTH_SOCK` globally for every client If you want to persist and automatically configure the `SSH_AUTH_SOCK` environment variable for every client without launching them from the terminal, run the following snippet to create a login script in `/etc/profile.d/`: ```shell echo "export SSH_AUTH_SOCK=~/.1password/agent.sock" | sudo tee /etc/profile.d/1password-ssh-auth-sock.sh ``` If your system launches the GNOME keyring SSH agent automatically, you can disable that by running the following command: ```shell mkdir -p ~/.config/autostart \ && cp /etc/xdg/autostart/gnome-keyring-ssh.desktop ~/.config/autostart/gnome-keyring-ssh.desktop \ && echo "Hidden=true" >> ~/.config/autostart/gnome-keyring-ssh.desktop ``` If you choose not to do this, the GNOME setting (`/run/user/1000/keyring/ssh`) may take precedence over the 1Password setting, depending on your operating system. ### Using Git autofetch {#git-autofetch} Some Git clients are configured by default to periodically perform a `git fetch` in the background. This can result in authorization prompts popping up unexpectedly, so 1Password helps to suppress prompts if the application or window where the request came from isn't in the foreground. If a prompt has been suppressed, you'll see an indicator dot on the 1Password icon in your device's menu bar, taskbar, or system tray. To access the prompt, select the 1Password icon, then select **SSH request waiting**. The authorization prompt will be brought to the foreground, where you can approve or deny the request. If you'd rather not be prompted when your applications automatically fetch changes, even when the prompts are suppressed, you can turn off the autofetch settings in your Git client and instead only fetch or pull on demand. _[Turn on the settings in 1Password to make sure the agent keeps running]_ ### Setting public keys as `IdentityFile` {#identity-file} If an SSH client supports setting public keys as `IdentityFile`, you can use that to [match hosts to a specific key in 1Password](/docs/ssh/agent/advanced#match-key-with-host). In the list below, you can see if that's the case for your preferred SSH client. --- ## OpenSSH {#openssh} **Mac:** #### `ssh`, `sftp`, `scp` workflows with jump hosts (`-J`, `ProxyJump`, `ProxyCommand`). workflows that use agent forwarding (`ForwardAgent`). #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). **Windows:** #### `ssh`, `sftp`, `scp` #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). **Linux:** #### `ssh`, `sftp`, `scp` workflows with jump hosts (`-J`, `ProxyJump`, `ProxyCommand`). workflows that use agent forwarding (`ForwardAgent`). #### `ssh-add` listing identities (`-l` and `-L`). locking and unlocking (`-x` and `-X`). adding and deleting identities (`ssh-add path/to/key`, `-d`, and `-D`). ## Celestial Software {#celestial-software} **Windows:** ## Cyberduck {#cyberduck} **Mac:** **Windows:** ## DataGrip {#datagrip} **Mac:** **Linux:** ## FileZilla {#filezilla} **Mac:** **Windows:** ## Fork {#fork} **Mac:** **Windows:** ## ForkLift {#forklift} **Mac:** ## `git` CLI **Mac:** **Windows:** For Git compatibility on Windows, see [Git for Windows](#git-for-windows). **Linux:** ## Git for Windows {#git-for-windows} **Windows:** PowerShell and `cmd`. > **Tip:** > For WSL, workarounds exist to forward socket connections using `npiperelay` and `socat`. ## Gitfox {#gitfox} **Mac:** ## GitHub Desktop {#github-desktop} **Mac:** **Windows:** using it when GitHub account is connected/logged in. ## GitKraken {#gitkraken} **Mac:** **Windows:** **Linux:** ## JetBrains IDEs {#jetbrains-ide} *IntelliJ IDEA, WebStorm, GoLand, CLion, PhpStorm, RubyMine, AppCode.* **Mac:** **Windows:** **Linux:** ## Nova {#nova} **Mac:** ## Pageant {#pageant} **Windows:** using the agent from Pageant. > **Tip:** > Workarounds and open-source tools exist to forward Pageant requests to the OpenSSH agent pipe. ## Postico {#postico} **Mac:** > **Tip:** > As a workaround, you can set up the SSH tunnel from your terminal and then configure Postico to connect over `localhost`. ## PuTTY {#putty} **Windows:** ## Sequel Ace {#sequel-ace} **Mac:** > **Tip:** > As a workaround, you can set up the SSH tunnel from your terminal and then configure Sequel Ace to connect over `localhost`. ## Sourcetree {#sourcetree} **Mac:** **Windows:** ## Sublime Merge {#sublime-merge} **Mac:** **Windows:** **Linux:** ## TablePlus {#tableplus} **Mac:** {/* **Windows:** */} {/* **Linux:** */} ## Termius {#termius} **Mac:** **Windows:** **Linux:** ## Tower {#tower} **Mac:** **Windows:** using it when GitHub account is connected/logged in. ## Transmit {#transmit} **Mac:** ## Visual Studio Code {#vs-code} **Mac:** **Windows:** **Linux:** ## Xcode {#xcode} **Mac:** --- ## SSH agent config file The 1Password SSH agent config file is a [TOML file](https://toml.io/en/) you can create that gives you more fine-grained control over the behavior of the SSH agent. With the agent config file, you can: - [Choose which keys are available to the SSH agent](#add-individual-keys) from any of your vaults and accounts, not just your Personal, Private, or Employee vault. - Specify the order the agent uses to offer your keys to SSH servers, to prevent running into the [six-key authentication limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit) on most servers. - Create different agent configurations for each machine, to customize how you use the SSH agent on each device. The SSH agent config file (`~/.config/1Password/ssh/agent.toml`) is unique to 1Password. It's separate from the SSH *client* config file ([`~/.ssh/config`](https://linux.die.net/man/5/ssh_config)) and the SSH *server* config file ([`/etc/ssh/sshd_config`](https://linux.die.net/man/5/sshd_config)) and can be used alongside them. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) ## About the SSH agent config file The SSH agent config file is an optional configuration file that allows you to override the [default behavior](#agent-configuration-options) of the 1Password SSH agent on your Mac, Windows, or Linux machine. It doesn't alter your SSH agent settings or other SSH config files on your computer — only which keys the agent can access and in which order to make them available to servers. The agent config file is saved locally on your machine and isn't synced to the 1Password servers. If you use 1Password with multiple workstations, you can sync or share the agent config file using your own method (for example, using Git) the same way you do with other dotfiles. Or you can create separate agent config files for each machine. You can [remove the agent config file](#remove-the-ssh-agent-config-file) at any time to return to the default agent configuration. ### Agent configuration options If there's no agent config file on your machine, 1Password will use the default SSH agent configuration, which allows the agent to make any SSH key item in your default [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault available to offer to SSH servers. If you want to customize how the SSH agent is configured, you can [create the SSH agent config file](#create-the-ssh-agent-config-file) to override the default agent behavior, then [modify the file](#modify-the-ssh-agent-config-file) to specify which keys the SSH agent has access to and the order you want them offered to the server. ### File syntax and structure #### TOML syntax The SSH agent config file uses the [TOML file syntax](https://toml.io/en/v1.0.0) to identify which SSH keys the SSH agent can access and when it can access them. Each entry in the file requires an `[[ssh-keys]]` header and one or more key-value pairs to indicate the item, vault, and/or account name or ID for the SSH key item. For example: ```toml title=agent.toml # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" vault = "Work" # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" # Then add all keys from my Private vault [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` **TOML syntax rules** The SSH agent config file adheres to the following TOML syntax rules: - **Case sensitivity:** TOML is case-sensitive, so all TOML elements (the header name and keys in key-value pairs) must be lowercase. Strings (1Password values enclosed in quotation marks) and comments are not case-sensitive. - **Encoding:** The TOML file must use valid [UTF-8 character encoding](https://www.ietf.org/rfc/rfc3629.txt). - **Comments:** Use the hash (#) symbol to indicate the line is a comment. Comments are optional and are not case-sensitive. For example: ``` # This line is a comment. ``` - **Header name:** Indicates the start of a new section and must be lowercase and enclosed in double brackets to indicate an array of tables. Each header must use the same name `[[ssh-keys]]` header name to define it as part of the array. - **Key-value pairs:** Indicate which SSH key items are available to the SSH agent. Keys must be lowercase and can be one or more of `item`, `vault`, or `account`. Values are the strings containing the item, vault, or account name or ID from 1Password and must be enclosed in quotes. Key-value pairs are separated by an equal (=) sign and each pair must be on a new line. Unspecified values are invalid. For example: ``` item = "My SSH key item name" ``` - **Whitespace:** Leading and trailing whitespace of both `key` and `value` segments are ignored, so `key = "value"` is parsed the same as `key="value"`. #### Examples of good TOML file entries ```toml variant="good" # My work GitHub SSH key [[ssh-keys]] item = "GitHub SSH key - Work" ``` The example above meets all the syntax criteria. ```toml variant="good" # My team's demo GitHub SSH key [[ssh-keys]] item="GitHub SSH key - Demo" vault="Demo" account="AgileBits" ``` Whitespace is ignored for key-value pairs, so this example is also good. #### Examples of bad TOML file entries ```toml variant="bad" # My work GitHub SSH key [[SSH-KEYS]] ITEM = "GitHub SSH key - Work" ``` The example above doesn't respect the case sensitivity for TOML elements — `[[ssh-keys]]` and `item` need to be lowercase. ```toml variant="bad" # My work GitHub SSH key item = "github ssh key - work" ``` In this example, the `"github ssh key - work"` value is good because 1Password values aren't case sensitive, but the entry is missing the required `[[ssh-keys]]` header. ```toml variant="bad" # My team's demo GitHub SSH key [[ssh-keys]] item = GitHub SSH key - Demo vault = Demo account = AgileBits ``` In the example above, the values for `item`, `vault`, and `account` aren't enclosed in quotations. For more information about TOML, see the [full list of specifications](https://toml.io/en/v1.0.0). #### File structure The SSH agent config file is made up of sections. A section is defined by the `[[ssh-keys]]` header followed by one or more key-value pairs for the intended SSH key or set of keys to be made available to the SSH agent. The order of the `[[ssh-keys]]` sections in the agent config file determine the order the agent offers your keys to SSH servers. This helps to minimize the number of authentication attempts the SSH agent makes so you don't run into the [six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit) (`MaxAuthTries`) that is the default for most SSH servers. Here's an example of an SSH agent configuration file with entries for two specific SSH keys: ```toml agent.toml {3,9} # My GitHub SSH key for my Work account [[ssh-keys]] item = "GitHub SSH key - Work" vault = "Private" account = "AgileBits" # Shared GitHub SSH key for the Demo account [[ssh-keys]] item = "GitHub SSH Key - Demo" vault = "Demo" account = "AgileBits" ``` With this configuration, if you try to SSH into a GitHub repository in your `Work` account, the SSH agent will offer your work SSH key to the server first because it's the first key entry in the file. If the key is a match, 1Password will ask you to [authorize the request](/docs/ssh/get-started#step-6-authorize-the-ssh-request). If you try to SSH into a GitHub repository in your `Demo` account instead, the agent will still offer your work key to the server first, then your demo SSH key. With only two SSH keys in the file, it's unlikely that you'd be at risk of running into any server limits. However, if you have six or more SSH keys listed in your agent config file before the demo key, or if your agent config file includes multiple SSH keys for the same host, you can also modify the SSH client config file (`~/.ssh/config`) to [match your SSH keys to individual hosts](/docs/ssh/agent/advanced#match-key-with-host) or specify [which SSH key each of your GitHub repositories uses](/docs/ssh/agent/advanced#use-multiple-git-identities-on-the-same-machine). ## Create the SSH agent config file ### From the 1Password app You can use the 1Password desktop app to create the SSH agent config file for you. The file will include entries to allow the SSH agent to access all the keys in any of your Personal, Private, or Employee vaults, similar to the [default configuration](#agent-configuration-options) used by the agent when no agent config file exists. For example, if you're signed in to a 1Password account with a default Private vault, you'll see an entry like this added to the agent config file: ```toml [[ssh-keys]] vault = "Private" ``` You can then choose to [modify the file](#modify-the-ssh-agent-config-file) to adjust which keys the agent offers to SSH servers in which order. To create the agent config file from 1Password: **Mac:** 1. Open and unlock [1Password for Mac](https://1password.com/downloads/mac) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On macOS, 1Password will create the SSH agent config file in the following location: ```text ~/.config/1Password/ssh/agent.toml ``` 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. **Windows:** 1. Open and unlock [1Password for Windows](https://1password.com/downloads/windows) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On Windows, 1Password will create the SSH agent config file in the following location: ```text %LOCALAPPDATA%/1Password/config/ssh/agent.toml ``` After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. **Linux:** 1. Open and unlock [1Password for Linux](https://1password.com/downloads/linux) and select any SSH key you want to add to the agent config file. If you don't have any SSH keys saved in 1Password yet, you can generate a new key in 1Password or import an existing key. 2. Select > **Configure for SSH Agent**. This will automatically create the SSH agent config file and open it in your default editor. You can then [modify the config file](#modify-the-ssh-agent-config-file) to add the SSH key. _[Create the SSH agent config file from the app]_ On Linux, 1Password will create the SSH agent config file in the following location: ```text ~/.config/1Password/ssh/agent.toml ``` 1Password also supports the `XDG_CONFIG_HOME` environment variable, if you have it configured. After you create the file, you may need to lock and then unlock 1Password for the agent config file to be recognized. ### From the terminal You can also choose to create the SSH agent config file yourself from the terminal. The file won't include any entries for your SSH keys — including any keys in your default Personal, Private, or Employee vault(s) — until you add them. When you create the file at the specified path, 1Password will detect it and override the default agent behavior, even if the agent config file is empty. Make sure to [modify the agent config file](#modify-the-ssh-agent-config-file) after you create it, to add any SSH keys items you need from any of your vaults or accounts. You can create the SSH agent config file on your machine at the specified path: **Mac:** On macOS, 1Password will look for the SSH agent config file at: ```text ~/.config/1Password/ssh/agent.toml ``` If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: ```text $XDG_CONFIG_HOME/1Password/ssh/agent.toml ``` **Windows:** On Windows, 1Password will look for the SSH agent config file at: ```text %LOCALAPPDATA%/1Password/config/ssh/agent.toml ``` **Linux:** On Linux, 1Password will look for the SSH agent config file at: ```text ~/.config/1Password/ssh/agent.toml ``` If you have the `XDG_CONFIG_HOME` environment variable configured, 1Password will check the following path first: ```text $XDG_CONFIG_HOME/1Password/ssh/agent.toml ``` ## Modify the SSH agent config file You can make your SSH keys available to the SSH agent by adding `[[ssh-keys]]` sections to the agent config file for any combination of individual keys, vaults, and accounts you have access to in 1Password, including shared and custom vaults. Your `[[ssh-keys]]` entries can be as specific or as broad in scope as you'd like, where you'll use at least one or more of the following key-value pairs to act like a series of queries on your SSH key items: - item: "The item name or ID" - vault: "The vault name or ID" - account: "The account name sign-in address or ID" These key-value pairs work like `WHERE`/`AND` clauses and operators, where the more data you include, the more specific your query becomes. If the SSH agent finds more than one key match per entry, the keys will be added in ascending order according to when the item was created (from the oldest to the most recent). To control the exact order, you can add additional `[[ssh-keys]]` sections to the agent config file. Before you modify the agent config file, make sure you're familiar with the [file syntax and structure](#file-syntax-and-structure), to ensure the SSH agent behaves as you expect it to. You don't need to restart the SSH agent each time you edit the agent config file. Your saved changes will be immediately available to the agent. ### Add individual keys You can add an `[[ssh-keys]]` section for an individual SSH key by including an `item` key-value pair in the entry. Include additional key-value pairs if you want to further specify which vault or account the SSH key is in. For example: ```toml title=agent.toml # Add my Git authentication key from my Work vault [[ssh-keys]] item = "Git Authentication Key" # Then add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." ``` ### Add all keys in a vault You can add an `[[ssh-keys]]` section for all the SSH keys in a vault by including the `vault` key-value pair in the entry. You can include an `account` key-value if you want to specify which 1Password account the key is in, but don't include an `item` key-value pair or only that item will be added. For example: ```toml title=agent.toml # Add all keys from my Work vault [[ssh-keys]] vault = "Work" # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" ``` If you add or remove SSH keys from the vault, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Add all keys in an account You can add an `[[ssh-keys]]` section for all the SSH keys in a 1Password account by including the `account` key-value pair in the entry. Don't include the `item` or `vault` key-value pairs or you'll only add SSH keys for that item or vault. For example: ```toml title=agent.toml # Add all keys from my family account [[ssh-keys]] account = "Wendy Appleseed's Family" # Then add all keys from my work account [[ssh-keys]] account = "ACME, Inc." ``` Instead of the account name, you can also use the [sign-in address](https://support.1password.com/1password-glossary#sign-in-address) as the `account` value (sign-in addresses can include `https://` at the start, but it's not required). For example: ```toml title=agent.toml # Add all keys from my family account [[ssh-keys]] account = "my.1password.com" # Then add all keys from my work account [[ssh-keys]] account = "https://acme.1password.com" ``` If you add or remove SSH keys from the account, access to the keys will be added to, or removed from, the SSH agent without needing to modify the agent config file later. ### Filter keys You can use the `[[ssh-keys]]` entries as filters in the agent config file to progressively add keys for the SSH agent to access in your preferred order. When you have multiple 1Password accounts, like a work account and a family account, you can progressively filter the `[[ssh-keys]]` entries down by 1Password account. If you have any specific items or vaults that you want the SSH agent to offer to servers first, you can include those as well. For example: ```toml title=agent.toml # Add my Git signing key from my Work vault [[ssh-keys]] item = "Git Signing Key" vault = "Work" account = "ACME, Inc." # Then add all keys from the Private vault in my family account [[ssh-keys]] vault = "Private" account = "Wendy Appleseed's Family" # Then add all keys from the Private vault in my work account [[ssh-keys]] vault = "Private" account = "ACME, Inc." # Then add all remaining keys from any vault in my family account [[ssh-keys]] account = "Wendy Appleseed's Family" ``` ### Use IDs as values Using the name of an item, vault, or account in the agent config file makes it easier to identify what the entry is for. However, you might choose to use an ID in place of a name if: - **You don't want your item, vault, or account names stored in plaintext on disk.** [This metadata is encrypted](https://support.1password.com/1password-privacy#data-saved-in-1password:~:text=Your%20metadata%20is%20private) by default in 1Password, but the agent config file on your device is unencrypted. - **You expect the name of an item, vault, or account to be updated periodically.** IDs are the most stable way to reference an item. An item's ID only changes if you move it to a different vault. An example entry with an item ID: ```toml title=agent.toml {3} # Add my signing key from my Private vault [[ssh-keys]] item = "hhaeohhhc7iksdbadbx5pxyb6m" ``` To find and copy an item ID, go to the [**Advanced** settings](onepassword://settings/advanced) in the 1Password app and turn on **Show debugging tools**. Find the item you want and select it, then select > **Copy UUID**. Then paste the UUID value in the config file entry. You can also [use 1Password CLI to find the IDs for your items, vaults, and accounts](/docs/cli/reference#unique-identifiers-ids). ## Remove the SSH agent config file If you no longer want to use the SSH agent configuration file, you can delete the file or move it to another location. The 1Password SSH agent will then use the [default configuration](#agent-configuration-options) again. ## Get help To get help or provide feedback, use the `#ssh-agent-config` channel on the [1Password Developers Slack workspace](https://developer.1password.com/joinslack). This channel is used as the primary means of communication about the agent config file and is where we'll post updates and help answer questions. Errors in the agent config file If there's an error in the agent config file, the SSH agent will stop running and will notify you of the error in the [Developer settings](onepassword://settings/developers) of the 1Password app. Make sure each entry [uses the correct syntax](#file-syntax-and-structure). If you don't see an error message in 1Password but you're seeing an authentication error in your SSH client or having trouble using the SSH agent, check the values from your key-value pairs. If you make any typos in an item, vault, or account name value, the SSH agent won't be able to make a key match. Entries without key matches are not considered errors and will be ignored. If you're not able to use a specific key with the SSH agent and it's in the agent config file with the correct syntax and values, you can also check that the SSH key hasn't been archived or deleted. Any archived or deleted SSH Key items will be ignored, even if you specify them by ID. To see the list of all keys the SSH agent can access, you can run the `ssh-add -l` command, with the `SSH_AUTH_SOCK` environment variable set to the agent socket path: **Mac:** ```sh SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ssh-add -l ``` **Windows:** ```sh ssh-add -l ``` **Linux:** ```sh SSH_AUTH_SOCK=~/.1password/agent.sock ssh-add -l ``` ## Learn more - [Get started with 1Password for SSH & Git](/docs/ssh/get-started/) - [Advanced use cases](/docs/ssh/agent/advanced/) - [Manage SSH keys](/docs/ssh/manage-keys#generate-an-ssh-key) - [SSH client compatibility](/docs/ssh/agent/compatibility/) - [About 1Password SSH Agent security](/docs/ssh/agent/security/) --- ## SSH agent forwarding with 1Password SSH agent forwarding lets you make SSH requests within a remote environment as if it were your local machine, like running Git commands and signing commits from a [cloud development environment](#cde) or [remote workstation](#remote-workstation). Instead of storing your private keys on the remote host, you can use SSH agent forwarding to forward your requests to your local 1Password SSH Agent. Then authorize the request with biometrics without your private keys ever leaving the local 1Password process. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and make sure it's running on your local machine. :::tip If you use Windows If you use a Windows computer, you can [set up the 1Password WSL integration](/docs/ssh/integrations/wsl) to authenticate SSH requests in your WSL instance from your Windows host. ::: ## About SSH agent forwarding When you enable agent forwarding for a remote host, every SSH request you make within the remote environment gets forwarded to the local 1Password process over the 1Password SSH Agent socket. You can authorize SSH requests locally using options you've set up in 1Password, like your fingerprint. Then your authorization gets forwarded back to the remote host without ever needing to provide your private key to the remote server. :::caution Make sure you only use SSH agent forwarding with trusted hosts. [Learn how to use SSH agent forwarding more securely.](#security) ::: ## Set up SSH agent forwarding {#set-up} SSH agent forwarding is turned off in OpenSSH by default. You can choose to turn it on for a [single session](#for-a-single-session) or for a [specific host](#for-a-specific-host). ### For a single session To turn on agent forwarding for a single session only, use the `-A` flag with the `ssh` command: ```shell ssh -A user@example.com ``` When you're connected to the remote host with agent forwarding turned on, the `SSH_AUTH_SOCK` environment variable on the remote host is automatically set. Data sent over this socket gets forwarded to the local 1Password socket. ```text user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` To check if agent forwarding is working, run the following command view a list of the SSH keys forwarded from 1Password to the remote host: ```text user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you see your SSH key listed, try to run an SSH request from within the remote server: ```text user@example.com:~$ ssh -T git@github.com ``` The 1Password app on your local machine should prompt you to authorize the request. ### For a specific host If you want to set up SSH agent forwarding for a specific host all the time so you don't need to use the `-A` flag for each session, edit your `~/.ssh/config` file to include that host: ```text Host example.com ForwardAgent yes ``` ## SSH agent forwarding security {#security} ### Security considerations When you authorize your local terminal, IDE, or other SSH client to use an SSH key in an agent forwarding session, any new connection made within the remote environment using the same key is also authorized. If someone else were to gain access to the remote environment as the same OS user, they'd be able to use the SSH key to authenticate connections from the remote host for the duration of the session. However, any other SSH keys available in the remote environment still require your approval before they can be used. Unlike the standard OpenSSH agent, where every key in the agent can be used in the remote environment without additional authorization, the 1Password SSH Agent requires your approval for each SSH key before it can be used. An attempt to use one of those keys from the remote environment triggers a 1Password authorization prompt that needs to be authenticated, making agent forwarding more secure with 1Password than with the OpenSSH agent. ### Use agent forwarding more securely We recommend the following: - Only use agent forwarding when you need it and in environments that you trust are secure. - Set up agent forwarding on a [per-command basis](#for-a-single-session) or configure your `~/.ssh/config` file to allow agent forwarding [only with specific hosts](#for-a-specific-host). **Do not turn on SSH agent forwarding for all hosts by default.** ```text variant="bad" title="~/.ssh/config (bad 👎)" Host * ForwardAgent yes ``` We recommend that you always scope the `ForwardAgent yes` directive down to a specific host or domain you trust for agent forwarding. For example, to turn on agent forwarding for [Gitpod ](https://www.gitpod.io/): ```text variant="good" title="~/.ssh/config (good 👍)" Host *.gitpod.io ForwardAgent yes ``` ## Use case: Cloud Development Environment {#cde} If you use a local integrated development environment (IDE) to connect to a cloud development environment (CDE) and you want to pull, push, and sign remote Git commits, you can authenticate those commands through the local 1Password SSH Agent. For example, you might have an IDE desktop app on your local workstation that you use to authenticate into a cloud-based development environment. You want to use the the CDE workspace to access remote Git repositories and you need to be able to authenticate Git requests and sign commits. With SSH agent forwarding, you can authenticate SSH and Git commands from your CDE workspace in your IDE desktop app through the 1Password SSH Agent running on your local workstation. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize Git requests from your cloud development environment, [edit your SSH config file to add your CDE host](#for-a-specific-host). The remote development integration in your IDE should recognize this automatically. To check if agent forwarding is correctly set up, open a remote shell in your IDE then run the following command: ```shell ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Use SSH for Git authentication If your CDE is set up to use HTTPS to authenticate with Git and you want to use SSH instead, run the following command to modify the remote Git configuration for the CDE: ```shell git config --global url."ssh://git@".insteadOf "https://" ``` Alternatively, you can add the command to your cloud development initialization (cloud-init) script or dotfiles. The next time you make a Git request from your CDE, 1Password should prompt you to authorize the request. For example: ```shell git fetch ``` If you only want to use SSH authentication going forward, you may want to revoke HTTPS write access to your repository. ### Set up Git commit signing {#git-commit-signing-cde} Your local `.gitconfig` file isn't automatically forwarded to your cloud development environment, so you'll need to modify the Git configuration in your CDE to set up remote Git commit signing. 1. Configure Git to use SSH for commit signing: ```shell git config --global gpg.format ssh ``` 2. Tell Git to always sign commits: ```shell git config --global commit.gpgsign true ``` 3. Set the SSH key you want to use to sign commits: ```shell git config --global user.signingkey ``` ### Authorization model {#authorization-model-cde} When you run an SSH or Git request in your cloud development environment that requires authorization, 1Password will prompt you to approve SSH key usage for the IDE that's connected to your CDE. If you approve the request, the entire IDE will be authorized to use that key. Any process running on the cloud development environment under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Use case: Remote workstation {#remote-workstation} If you have a remote workstation that you connect to over SSH, and you want to run SSH and Git requests from that workstation, you can authenticate those requests through the 1Password agents that runs on your local host. For example, you might have a desktop workstation at home that contains all your Git repositories. You want to work on the go, so you use your laptop to connect to your remote workstation over SSH so you can work in your Git repos. With SSH agent forwarding, you can authenticate SSH and Git commands from your remote workstation through the 1Password SSH Agent running on your local laptop. ### Set up SSH agent forwarding To set up SSH agent forwarding so you can authorize SSH and Git requests from your remote workstation, [edit the SSH config file](#for-a-specific-host) on your local host to allow agent forwarding with your remote workstation. To check if agent forwarding is correctly set up, connect to your remote workstation then run the following command: ```shell ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` You should see a list of the SSH keys the agent can use for SSH requests. ### Modify the `IdentityAgent` configuration on the remote workstation If your remote workstation also has the 1Password SSH Agent installed, you'll want to make sure that Git and SSH use the forwarded socket from your local host instead of the agent socket for the 1Password app installed on the remote workstation. The `IdentityAgent` takes precedence over the `SSH_AUTH_SOCK` environment variable, so you may want to modify the `~/.ssh/config` file for your remote workstation so the `IdentityAgent` setting is only applied if you're not in an SSH shell. ```text Match host * exec "test -z $SSH_TTY" IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` Then any Git or SSH command executed from an SSH shell on the remote workstation will use the forwarded `SSH_AUTH_SOCK` for authentication and 1Password should prompt you to authorize SSH requests from your local host. This change won't affect how the 1Password SSH Agent runs when you use the workstation locally instead of accessing it remotely. The `IdentityAgent` setting will be applied as usual to use the SSH agent running on the workstation. ### Set up Git commit signing Your local `.gitconfig` file isn't automatically forwarded to your remote workstation, so the remote Git configuration will be used by default. If you've configured [Git commit signing with 1Password](/docs/ssh/git-commit-signing) on the remote workstation using the same SSH key you use on your local host, you shouldn't need make any changes to your setup. If the `op-ssh-sign` signing program finds that both the `SSH_AUTH_SOCK` and the `SSH_TTY` environment variables are set, it will automatically adapt to use the forwarded socket from your local host instead of the 1Password socket from your remote workstation. ### Authorization model {#authorization-model-remote-workstation} When you run an SSH or Git request from a remote shell or remotely connected IDE that requires authorization, 1Password will prompt you to approve SSH key usage for the terminal or IDE you use to connect to the remote workstation. If you approve the request, the entire app will be authorized to use this key. Any process running on the remote workstation under the same OS user will also be authorized, which is a [security consideration](#security) to keep in mind. ## Troubleshooting If you're having trouble using agent forwarding with the 1Password SSH Agent, there are a few things you should check. ### Check if the `SSH_AUTH_SOCK` environment variable is set Run `echo $SSH_AUTH_SOCK` in the terminal to make sure the environment variable is set on your server. ```text user@example.com:~$ echo $SSH_AUTH_SOCK #code-result /tmp/ssh-XXXXNpdlnL/agent.151 ``` If the variable isn't set, SSH agent forwarding won't work. Make sure [the 1Password SSH Agent is turned on](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and that you've [configured your SSH client to use the agent for authentication](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client). ### Check if the SSH agent can access the correct SSH key Run `ssh-add -l` in the terminal to see a list of the SSH keys forwarded from 1Password to the remote host: ```text user@example.com:~$ ssh-add -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI SSH Key from 1Password (ED25519) ``` If you don't see your SSH key listed, make sure the key is [eligible to use with the 1Password SSH Agent](/docs/ssh/agent#eligible-keys) and that it's [saved in a vault the SSH agent is configured to use](/docs/ssh/agent#configuration). ### Check if agent forwarding is allowed on the server To use agent forwarding with a remote server, the `AllowAgentForwarding` option must be set to `Yes` in the [`sshd_config` file](https://man.openbsd.org/sshd_config) for the server. --- ## 1Password SSH agent The 1Password SSH agent uses the SSH keys you have saved in 1Password to seamlessly integrate with your Git and SSH workflows. It authenticates your Git and SSH clients without those clients ever being able to read your private key. In fact, your private key never even leaves the 1Password app. The SSH agent works with the SSH keys stored in 1Password, but never without your consent. Only SSH clients you explicitly authorize will be able to use your SSH keys until 1Password locks. Learn how to [turn on the 1Password SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) and [configure your SSH clients](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client). ## Requirements **Mac:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Windows:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Linux:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. :::warning[caution] The 1Password SSH agent doesn't work with [Flatpak ](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). ::: :::tip For the best experience when using the 1Password SSH agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ::: ## Configuration By default, the 1Password SSH agent will make every [eligible key](/docs/ssh/agent#eligible-keys) in the built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault of your 1Password accounts available to offer to SSH servers. This configuration is automatically set up when you [turn on the SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent). If you need to use the SSH agent with keys saved in shared or custom vaults, you can create and customize an [SSH agent config file](/docs/ssh/agent/config/) (`~/.config/1Password/ssh/agent.toml`) to override the default agent configuration. If you have more than six SSH keys available in the agent, you can edit your SSH config file or use [SSH Bookmarks](/docs/ssh/bookmarks/) to match your keys to specific hosts. This will help you avoid authentication failures with OpenSSH servers that limit the number of connection attempts. Learn more about the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ## Eligible keys For the 1Password SSH agent to work with your SSH keys, your 1Password SSH key items must meet the following requirements. They must be: - [Generated](/docs/ssh/manage-keys#generate-an-ssh-key) or [imported](/docs/ssh/manage-keys#import-an-ssh-key) using the `SSH Key` item type (which supports [`Ed25519` or `RSA`](/docs/ssh/manage-keys#supported-ssh-key-types) key types). - Stored in the vaults [the SSH agent is configured to use](#configuration) in 1Password. By default, this is the [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault of any 1Password account you're signed in to. - Active items (not archived or deleted). Any key meeting these requirements will automatically be available in the SSH agent for authentication. You will still be required to explicitly [authorize any request](/docs/ssh/agent/security#authorization-model) an SSH client makes to use your keys. To see a list of all keys that the agent has available, [set the `SSH_AUTH_SOCK` environment variable](/docs/ssh/get-started#step-4-configure-your-ssh-or-git-client) (Mac and Linux only) and run: ```shell ssh-add -l ``` --- ## About 1Password SSH Agent security The 1Password SSH Agent allows you to securely authenticate all your Git and SSH commands from 1Password. Your private keys never leave 1Password, are never stored locally, and are never used without your consent. ## Differences with the OpenSSH agent The standard OpenSSH agent (`ssh-agent`) that comes preinstalled on most operating systems requires you to add keys to the agent (`ssh-add`) every time it launches. After you've added your SSH keys, any process can use any key that the OpenSSH agent is managing. It's then up to you to remove those keys when they're not needed anymore. The 1Password SSH Agent uses a different approach and asks for your consent before an SSH client or terminal session can use your key. Because of this, there's no concept of adding or removing keys like with the OpenSSH agent. When you [turn on the SSH agent](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) from the 1Password preferences or settings, every [eligible key](/docs/ssh/agent#eligible-keys) saved in 1Password becomes available to use for SSH, but your private keys will never be used without your consent. ## Authorization model {#authorization-model} ### About the authorization model The authorization model for the 1Password SSH Agent is built on the idea that you should be able to control which processes are allowed to use which private keys. When an SSH client or terminal session on your system makes a request through the SSH agent to use one of your keys, 1Password will ask if you want to approve the request. The authorization prompt indicates which process is requesting permission to use which SSH key. After you approve the request, a session is established between the key and the process the SSH command was run from (a process can be a terminal window or tab, an IDE, or a GUI application, like a Git or SFTP client). Any subsequent SSH commands run in that process can use your key without further approval until 1Password locks or quits, or for the amount of time set in the [options you've configured](#authorization-options). For example, if you authorize a `git pull` command from the terminal for one of your SSH keys, 1Password won't prompt you to approve your following `git push` because the session is already approved. When 1Password is locked, the SSH agent continues to run in the background and will prompt you if an SSH client tries to use one of your keys. If you've already authorized the client to use your key for a set amount of time (for example, four hours) instead of when 1Password locks, your approval will still be in the agent's memory and you'll only be prompted to unlock 1Password. The SSH agent doesn't keep your private keys in memory when 1Password is locked, only your authorization, so the app needs to be unlocked for the agent to access your private keys. ### Approving SSH key requests When the SSH agent requires your approval to use one of your keys, 1Password will show you an authorization prompt that lets you approve the request using options like Touch ID, Windows Hello, your 1Password account password, and more. The authorization method will vary depending on your device, operating system version, 1Password settings, and other factors, so the prompt will indicate how you can authorize the request. You'll also have the option to deny any request. If the SSH key you're approving belongs to an account that uses [1Password Unlock with SSO](https://support.1password.com/sso-get-started/), you may be redirected to the sign-in page for your identity provider. You'll then need to sign in using the credentials for your provider account to authorize the request. ### Authorization options The authorization model for the 1Password SSH Agent allows for some flexibility, so you can set it up to best suit your needs at any given time. You'll always be asked to authorize the use of each private key, but you can adjust options like how long an SSH agent session lasts (how long the agent remembers your key approval). This could be until 1Password locks or quits, or until a set amount of time has passed. You can also choose what usage you're approving for each key, which determines when the SSH agent will ask you to approve requests. With all options, your authorization grants access to an SSH key within that agent session, or until the application or terminal session quits. Usage options you can choose include: - **Per key, per application** (default): When you approve an SSH key request, you authorize a specific application (including all of it's subprocesses) to use a specific SSH key. - **Per key, per application, per terminal session**: When you approve an SSH key request, you authorize a specific application (including all of it's subprocesses) to use a specific SSH key, but with an additional restrictions. If the application is a terminal emulator or an IDE with a built-in terminal, your authorization only applies to a specific tab. Each new terminal tab in that application requires separate approval to use that key. - **Per key, once for every process running on the user’s system**: You can see this option on a per-request basis for a specific SSH key by selecting the **Approve for all applications** checkbox on the authorization prompt. This temporarily authorizes all processes running under the current OS user to use that key for the duration of the agent session. Access is only restricted by file permissions on the agent socket or named pipe. This option doesn't affect your other settings. [Learn how to adjust the authorization options for the 1Password SSH Agent.](/docs/ssh/get-started#adjust-your-authorization-options) ## Suppressing background requests It’s very common for IDEs and Git GUI clients to periodically run `git fetch` in the background on currently open repositories. This feature is often enabled by default and may result in unexpected authorization prompts from 1Password, especially if you're unaware of an application's auto-fetch behavior. 1Password helps to suppress prompts if it detects that the app or window the request originated from is not in the foreground. The 1Password icon in your device's menu bar, taskbar, or system tray will display an indicator dot when a prompt has been suppressed. If you need to access the prompt, select the 1Password icon and select **SSH request waiting**. The authorization prompt will be brought to the foreground. ## Local storage When you turn on the SSH agent, the 1Password app will store an unencrypted copy of the **public keys** of all your [eligible SSH keys](/docs/ssh/agent#eligible-keys) on disk. Storing your public keys allows the SSH authorization prompt to be shown even when 1Password is locked. If you turn on "Display key names when authorizing connections" for the SSH agent, the 1Password app will also store an unencrypted copy of your SSH key **item titles** on disk. Displaying SSH key names is optional and this setting is turned off by default. This setting can be turned on or off in the 1Password app. If the setting is turned off, your SSH key names will not be stored. The authorization prompt will instead show a truncated public key fingerprint for identification. --- ## Troubleshooting ## Create an SSH agent diagnostics report If you're experiencing issues with how the SSH agent handles your SSH requests, you can send us an SSH diagnostics report so we can help resolve the problem. You must use a [beta](https://support.1password.com/betas/) or nightly release of the 1Password app to create an SSH diagnostics report. ### Step 1: Set up SSH diagnostics recording To start recording SSH diagnostics, navigate to the 1Password data directory: **Mac:** ```text ~/Library/Group Containers/2BUA8C4S2C.com.1password/Library/Application Support/1Password/Data ``` **Windows:** ```text %LOCALAPPDATA%\1Password ``` **Linux:** ```text ~/.config/1Password ``` From this location, create a new subdirectory called `ssh-diagnostics`. SSH diagnostics recording is now enabled. ### Step 2: Run some SSH requests Run a few SSH requests using your preferred setup and tools to reproduce the issue you're having. Each SSH request you run will be logged as a pair of JSON files in the `ssh-diagnostics` directory. ### Step 3: Create a ZIP file of your `ssh-diagnostics` directory After you've recorded a few SSH requests that demonstrate the issue, create a ZIP file of your `ssh-diagnostics` directory. To stop recording, delete the `ssh-diagnostics` directory. ### Step 4: Remove personally identifiable information (PII) from the diagnostics files The files generated during the SSH diagnostics recording may contain PII, like your OS username, Git repo names, and SSH hosts. The 1Password app attempts to redact as much of this data as possible and you'll see things like ``, ``, and `` in the generated JSON files. However, there could still be some PII contained in your diagnostics files. Make sure to check for any information you don't want to include, like a company name that appears as part of a path, and redact it. Then recreate your ZIP file. --- ## Manage SSH Bookmarks in 1Password (beta) SSH Bookmarks in 1Password allow you to: - Connect to SSH hosts directly from 1Password, without manually entering commands in the terminal. - Match your SSH keys to specific hosts to make sure the correct key is used for each connection. - Avoid [server key limitations](/docs/ssh/agent/advanced#ssh-server-six-key-limit) when managing multiple SSH keys. You can add bookmarks from the [SSH activity log](https://support.1password.com/developer#ssh-activity-log) or by adding `ssh://` URLs to your SSH Key items. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) 5. [Turn on 1Password Developer.](https://support.1password.com/developer#turn-on-1password-developer) ## Manage your SSH Bookmarks You can use and manage SSH Bookmarks for hosts that use keys [available to the 1Password SSH agent](/docs/ssh/agent#eligible-keys). If you're signed in to [multiple accounts](https://support.1password.com/multiple-accounts/) in the 1Password desktop app, make sure to unlock the accounts where you've stored the keys for your SSH hosts. ### Create a bookmark Create bookmarks for your frequently used SSH hosts from the [SSH activity log](#from-the-activity-log) or in an [SSH Key item](#in-an-ssh-key-item). #### From the activity log The quickest way to create a bookmark is to use the Bookmark option in the [SSH activity log](https://support.1password.com/developer#ssh-activity-log). You'll see a **Bookmark** button next to any `ssh` commands you've run from the terminal (like `ssh user@hostname`). 1. Open the 1Password desktop app. Select **Developer** in the sidebar, then select **View SSH agent**. If you don't see Developer in the sidebar, [turn on 1Password Developer](https://support.1password.com/developer#turn-on-1password-developer). 2. Navigate to the Activity section and find the entry for the SSH host you want to bookmark. 3. Select **Bookmark** in the Actions column. 1Password will add the SSH host URL to the associated SSH Key item, then add the bookmark to the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. #### In an SSH Key item If you want to create a bookmark for an SSH host that you haven't connected to recently, you can manually add a custom URL field to an SSH Key item. In 1Password, find the SSH Key item for the host you want to bookmark, then edit the item to add a [custom field](https://support.1password.com/custom-fields#add-a-custom-field) with the SSH host URL (a field label isn't required). The bookmark will be added to the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. SSH host URLs must start with `ssh://` and can use the hostname or IP address of the SSH host. If you've defined a `Host` block in your `~/.ssh/config` file with a custom alias (for example, `Host my-host-alias`), you can also bookmark the alias instead of the actual hostname or IP address. Examples of different types of bookmarks: - **Hostname**: `ssh://user@example.org`, `ssh://test-server.example.com` - **IP address**: `ssh://admin@192.0.2.255`, (IPv4), `ssh://user@2001:DB8:a8b0:5678::200c` (IPv6) - **Host alias**: `ssh://my-host-alias` ### Connect to a bookmarked host Connect to any of your bookmarked SSH hosts directly from the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page. To use a bookmark from the list, select **Connect**. 1Password will launch the terminal, which initiates a connection to the SSH host. Then [authorize the connection](https://developer.1password.com/docs/ssh/get-started#step-6-authorize-the-ssh-request), if prompted. 1Password uses the [terminal application](#terminal-for-ssh-connections) set for SSH URLs to connect to the host. ### Edit a bookmark From the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent developer page: 1. Select > **View SSH Key item** in the bookmark's Actions menu. 2. Select **Edit**, then update the host URL field. 3. Save your changes. Your saved changes will automatically update in your Bookmarks list. ### Remove a bookmark From the [Bookmarks](https://support.1password.com/developer#ssh-bookmarks) section of the SSH Agent page, select > **Remove bookmark** in the bookmark's Actions menu. You can also remove a bookmark by editing the SSH Key item. Remove the SSH host URL from the item, or delete the item if you no longer need the SSH key. Using either method removes an SSH Bookmark from your Bookmarks list, the SSH Key item, and the [1Password SSH configuration file](#ssh-bookmarks-config-file), if you turned on that feature. ## SSH Bookmarks config file 1Password can automatically manage an SSH config file (`~/.ssh/1Password/config`) that matches bookmarked SSH hosts with the corresponding SSH key. You can include this file in your main SSH config file (`~/.ssh/config`). This also prevents you from running into the [six-key server limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). Note that generating SSH configuration files will store your unencrypted SSH host URLs and SSH public keys for your bookmarks on disk. Your private keys will remain safe in 1Password. ### Generate the 1Password config file This feature is turned off by default, so you'll need to turn on the setting in 1Password: 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent (you may need to select the section to expand it). 3. Select **Generate SSH config files from 1Password SSH bookmarks**. If you see a message that says "Managed by administrator", the setting is managed by your team's [app usage policy](https://support.1password.com/team-policies#app-usage). Contact your team administrator to learn more. 1Password will generate a directory at `~/.ssh/1Password/` that includes: - `~/.ssh/1Password/config` file: An SSH configuration file that maps SSH hosts to their corresponding keys. - `*.pub` files: Individual public key files for each bookmarked host, named using the SSH key's public fingerprint. ### Use the configuration file To start using the 1Password configuration file, you'll need to include it in your main SSH config file. Add the following line to the top of your `~/.ssh/config` file: ```toml Include ~/.ssh/1Password/config ``` Then save your changes to the file. 1Password manages changes to the `~/.ssh/1Password/config` file. Any time you create, edit, or remove an SSH Bookmark, 1Password automatically updates the configuration file. If you want to override any of the rules from the 1Password configuration file, you can do so by editing your SSH configuration file. Copy the relevant `Match Host` block from the 1Password-generated `~/.ssh/1Password/config` file into your `~/.ssh/config` file. Then edit the configuration values in the block to your preferred values. If you turn off the setting to generate configuration files, 1Password will remove the `~/.ssh/1Password` directory and all generated files. :::caution Do not manually edit the 1Password-generated files Manual edits made to the 1Password-generated files won't be saved. If you need to make changes, [edit your SSH Bookmarks](#edit-a-bookmark) in 1Password or make the changes in your main `~/.ssh/config` file. ::: ## Terminal for SSH connections 1Password will use your system's default terminal application to launch SSH connections without additional setup, or you can choose your preferred terminal option in the settings. **Mac:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-mac} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select your preferred terminal application from the available options. **Windows:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-windows} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select the option you want 1Password to use to open SSH connections: Windows Terminal or a [custom terminal command](#set-custom-command-windows). #### Set a custom terminal command {#set-custom-command-windows} The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. Terminal commands are executed using the `cmd.exe /c start` process and can only contain simple command-line arguments. For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-windows). For example, if you want 1Password to use the Windows Terminal to open an SSH URL in a maximized window with a vertical, split-pane, you could use a command like: ``` wt.exe --maximized split-pane -V ssh %s ``` If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: ``` "C:\Program Files (x86)\My Terminal App\MyTerminalApp.exe" ssh %s ``` For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: ``` "C:\Scripts\MyScript.ps1" %s ``` :::info For more examples of Windows command-line arguments, see [Microsoft's documentation. ](https://learn.microsoft.com/en-us/windows/terminal/command-line-arguments?tabs=windows) ::: ##### SSH URL options and variables {#url-options-windows} You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: - `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) - `%u`: the user (`admin`) - `%h`: the host (`example.com`) - `%p`: the port (`9999`) If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: ``` my-command %s ``` If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: ``` my-command --user %u --host %h --port %p ``` The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: ``` my-command \%s ``` **Linux:** #### Choose a terminal option for SSH Bookmarks {#choose-terminal-linux} 1. Open the 1Password desktop app and navigate to **Settings** > [**Developer**](onepassword://settings/developers). 2. Go to the Advanced section for the SSH Agent and locate the **Open SSH URLs with** setting. 3. Select the option you want 1Password to use to open SSH connections: your preferred terminal application from the available options, a [custom terminal command](#set-custom-command-linux), or [xdg-open](#configure-xdg-open). If you want 1Password to handle your bookmarks separately from the rest of your system, you can choose your preferred terminal or a custom command in 1Password and configure `xdg-open` for your system. #### Set a custom terminal command {#set-custom-command-linux} The custom terminal command option allows you to provide your own shell command to open `ssh://` URLs. Terminal commands are executed using the `systemd-run` process and can only contain [simple command-line arguments. ](https://linux.die.net/man/1/bash) For more complex arguments that use environment variables or interpolation, you can create a script file and use the script's file path in your command. A basic command structure could include the terminal application, with any options and flags you want to use to specify the terminal's behavior, followed by the SSH command and [URL option(s)](#url-options-linux). For example, if you want 1Password to use the WezTerm terminal app to open an SSH URL in a new `tmux` session on a remote server, you could use a custom command like: ``` wezterm -e ssh %s tmux new -A ``` If your terminal app isn't in your `PATH`, use the full path of the app in your command. For example: ``` /home/my-apps/my-terminal-app ssh %s ``` For more complex arguments, you can create a custom script and use the full path of the script in your command. For example: ``` /home/user/scripts/my-custom-script.sh %s ``` ##### SSH URL options and variables {#url-options-linux} You can use one or more of the following options in your command to reference all or part of the SSH URL in your bookmark: - `%s`: the full SSH URL in your bookmark (for example: `ssh://admin@example.com:9999`) - `%u`: the user (`admin`) - `%h`: the host (`example.com`) - `%p`: the port (`9999`) If you want 1Password to use the full SSH URL syntax from your bookmark, use the `%s` option in your custom command: ``` my-command %s ``` If your SSH client doesn't support the SSH URL syntax, use the `%u` and `%h` options to pass the host and user variables separately when 1Password invokes your custom command: ``` my-command --user %u --host %h --port %p ``` The `--port %p` variable is optional. You don't need to include port information in your bookmark or custom command unless you need to use a port other than the default SSH port (`22`). If you don't want 1Password to replace an SSH URL option with a variable, add a backslash (`\`) before the option to escape it so it's treated as a literal string. For example: ``` my-command \%s ``` #### Configure `xdg-open` You can use `xdg-open` to open `ssh://` URLs with the application that registers the `x-scheme-handler/ssh` MIME type. To customize how `xdg-open` launches `ssh://` URLs, you can create a `.desktop` file: 1. Create a file called `1password-ssh-handler.desktop` in `~/.local/share/applications` with the following content: ```file {3} title=1password-ssh-handler.desktop [Desktop Entry] Name=1Password SSH Handler Exec=gnome-terminal -- ssh %u Terminal=false Type=Application MimeType=x-scheme-handler/ssh; ``` You can edit the `Exec` command to use your preferred terminal. 2. Run the following command in your terminal to register the SSH handler: ```shell update-desktop-database ~/.local/share/applications ``` ## Learn more - [Advanced use cases](/docs/ssh/agent/advanced/) - [SSH agent config file](/docs/ssh/agent/config/) - [Sign Git commits with SSH](/docs/ssh/git-commit-signing/) --- ## Get started with 1Password for SSH You can use 1Password to generate an SSH key and autofill your public key to your favorite Git platform. Then, set up the 1Password SSH agent and configure your SSH or Git client so you can use the 1Password SSH agent to authenticate your Git and SSH workflow. The following examples use GitHub to illustrate the SSH workflow from start to finish, but you can modify the steps to use with your favorite Git or cloud platform. ## Requirements **Mac:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Mac.](https://1password.com/downloads/mac) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Windows:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows.](https://1password.com/downloads/windows) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. **Linux:** 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Linux.](https://1password.com/downloads/linux) 3. [Install the 1Password browser extension](https://1password.com/downloads/browser-extension) (optional). Required to autofill SSH keys in your browser. :::warning[caution] The 1Password SSH agent doesn't work with [Flatpak ](https://flatpak.org/) or Snap Store installations of 1Password. To use the SSH agent, choose a different method to [install 1Password for Linux](https://support.1password.com/install-linux/). ::: :::tip For the best experience when using the 1Password SSH agent, you can configure [Touch ID](https://support.1password.com/touch-id-mac/), [Apple Watch](https://support.1password.com/apple-watch-mac/), [Windows Hello](https://support.1password.com/windows-hello/), or [system authentication](https://support.1password.com/system-authentication-linux/) to unlock 1Password and authenticate SSH key requests. ::: ## Step 1: Generate an SSH key 1. Open and unlock the 1Password app, then navigate to your **Personal**, **Private**, or **Employee** vault. The name of this vault varies depending on your account type. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Generate New Key**. 4. Select an SSH key type: [Ed25519 or RSA](/docs/ssh/manage-keys#supported-ssh-key-types), then select **Generate**. 5. When you're done, select **Save**. 1Password will generate your SSH key, which includes the private key, public key, and its fingerprint. _[Generating a new SSH Key item with the Ed25519 key type selected.]_ Learn more about [generating or importing SSH keys](/docs/ssh/manage-keys/) and [which SSH keys you can use with the 1Password SSH agent](/docs/ssh/agent#eligible-keys). ## Step 2: Upload your public key After you generate your SSH key, you can add the public key to your GitHub account. Visit the [GitHub SSH key settings page](https://github.com/settings/ssh/new) upload your public key using the 1Password browser extension or desktop app. **Browser extension:** 1. Select the **Title** or **Key** field on the GitHub settings page. If 1Password doesn't show a list of suggested items, select the 1Password icon in the field. 2. Select the GitHub SSH key you just created. 1Password will automatically fill the public key and title in the corresponding fields. 3. Select **Add SSH Key** on the settings page to save the key in your GitHub account. Your SSH key can now be used to authenticate with GitHub. For examples using other Git or cloud platforms, see [Autofill public keys](/docs/ssh/public-key-autofill/). _[The GitHub SSH key settings page in a browser, with the Key field selected on the page and the GitHub SSH key item selected in the 1Password popup.]_ **Desktop apps:** 1. Navigate to the GitHub SSH key you just created in 1Password and select it. 2. Copy your public key from the item details, then paste it into the **Key** field on the GitHub settings page. You can also use Quick Access to find and copy your public key. 3. Then select **Add SSH Key** on the settings page to save the key in your GitHub account. Your SSH key can now be used to authenticate with GitHub. For examples using other Git or cloud platforms, see [Autofill public keys](/docs/ssh/public-key-autofill/). _[A GitHub SSH Key item selected in the 1Password desktop app, with the public key field selected and ready to copy.]_ ## Step 3: Turn on the 1Password SSH agent The 1Password desktop app includes an SSH agent that, when turned on, runs in the background to handle authentication for your SSH clients. Follow these steps to turn on the SSH agent: **Mac:** 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **Developer**. 2. Select **Set Up SSH Agent**, then choose whether you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **General**. 2. Select the checkboxes to **Keep 1Password in the menu bar** and **Start at login**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ **Windows:** :::warning[caution] The 1Password SSH agent only works with SSH clients that support [Microsoft OpenSSH](https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_overview). For more information, see [SSH client compatibility](/docs/ssh/agent/compatibility/). ::: #### Check if the OpenSSH Authentication Agent service is installed and running Before you can turn on the SSH agent in 1Password, you'll need to check if the OpenSSH Authentication Agent service is installed: 1. Go to **Services** > **OpenSSH Authentication Agent** (press Win + R on your keyboard to open the Run window, type `services.msc` and press Enter or select **OK**). 2. Look for the **OpenSSH Authentication Agent** in the list of services. If you don't see the OpenSSH Authentication Agent in the list, skip ahead to the steps to [turn on the SSH agent in 1Password](/docs/ssh/get-started#turn-on-the-ssh-agent-in-1password). If you do see the OpenSSH Authentication Agent in the list, continue with these steps to disable it from startup and make sure it's not running: 3. Select **OpenSSH Authentication Agent** in the list of services and press Enter. 4. In the "Startup type" menu, select **Disabled**. If the service status shows the agent is running, select **Stop**. 5. Select **Apply** > **OK**. The 1Password SSH agent can then take over and listen on the system-wide pipe at `\\.\pipe\openssh-ssh-agent`. _[Stop the Windows OpenSSH Authentication Agent service]_ #### Turn on the SSH agent in 1Password Follow these steps to turn on the SSH agent in 1Password: 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. 2. Select **Set Up SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. 2. Select the checkbox to **Keep 1Password in the notification area**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ **Linux:** 1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. 2. Select **Set Up SSH Agent**, then choose whether or not you want to display SSH key names when you authorize connections. 3. (Optional) [Adjust the authorization options](#adjust-your-authorization-options) for when and how often the SSH agent will ask you to approve SSH requests. _[The SSH agent developer settings in the 1Password desktop app, with both checkboxes selected and a badge at the top that shows the agent is running.]_ If you previously turned off the SSH agent and would like to turn it back on, select the checkbox to **Use the SSH agent**. When you choose to display SSH key names when authorizing connections, it's easier for you to identify which key 1Password is requesting access to when authenticating a request from an SSH client. To display key names in authorization prompts, 1Password needs to [save the titles of your SSH Key items in local storage](/docs/ssh/agent/security#local-storage). To turn off this feature, deselect the checkbox to **Display key names when authorizing connections** in the Security section. To make sure the SSH agent keeps running, even when the 1Password app is closed: 1. Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **General**. 2. Select the checkbox to **Keep 1Password in the system tray**. _[The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running.]_ ## Step 4: Configure your SSH or Git client After you turn on the SSH agent in 1Password, you'll need to configure your SSH client to use the agent for authentication. **Mac:** Add the `IdentityAgent` snippet to your `~/.ssh/config` file: ``` Host * IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ``` If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: ```shell export SSH_AUTH_SOCK=~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ``` For an agent path that's easier to type, you can optionally run the following command to create a symlink for `~/.1password/agent.sock`: ```shell mkdir -p ~/.1password && ln -s ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ~/.1password/agent.sock ``` Now your SSH clients will use the 1Password SSH agent for all hosts. If you prefer to migrate to the 1Password SSH agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [gradual migration](/docs/ssh/agent/advanced#gradual-migration). Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/docs/ssh/agent/compatibility/). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). **Windows:** Additional configuration to use the SSH agent for authentication with your SSH clients isn't required. To use the SSH agent with Git, configure the [`core.sshCommand`](https://git-scm.com/docs/git-config#Documentation/git-config.txt-coresshCommand) variable in your Git config to use Microsoft OpenSSH: ``` git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe" ``` You can also manually edit your [`gitconfig` file](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#:~:text=On%20Windows%20systems): ``` [core] sshCommand = C:/Windows/System32/OpenSSH/ssh.exe ``` For the best Git experience with 1Password, install the latest version of [Git for Windows](https://gitforwindows.org/) (version `2.33` or later). If you're using Windows Subsytem for Linux (WSL), you can [use the 1Password SSH agent with WSL](/docs/ssh/integrations/wsl). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). **Linux:** Add the `IdentityAgent` snippet to your `~/.ssh/config` file: ``` Host * IdentityAgent ~/.1password/agent.sock ``` If your `~/.ssh` folder or `config` file doesn't exist yet, create it first. You can also set the `SSH_AUTH_SOCK` environment variable in the shell where your SSH command runs: ```shell export SSH_AUTH_SOCK=~/.1password/agent.sock ``` Now your SSH clients will use the 1Password SSH agent for all hosts. If you prefer to migrate to the 1Password SSH agent gradually, you can configure your SSH clients to only use the SSH agent for one or more specific hosts, instead of all hosts. Learn more about [advanced use cases](/docs/ssh/agent/advanced#gradual-migration). Some SSH clients don't support every configuration option that the `~/.ssh/config` file has to offer. Learn more about [SSH client compatibility](/docs/ssh/agent/compatibility/). By default, OpenSSH servers are configured to limit the amount of authentication attempts for an incoming SSH connection. Learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ## Step 5: Run a command Now you're ready to start using the 1Password SSH agent with GitHub. From your project directory, run: ``` git pull ``` If you don't have a project available on GitHub where you can run `git pull` now, you can run this command instead to quickly test your GitHub SSH setup: ``` ssh -T git@github.com ``` ## Step 6: Authorize the SSH request 1Password will ask you to allow your terminal or other SSH client to use your SSH key. You can approve this request using the authentication option indicated on the prompt (for example, Touch ID, Windows Hello, or your account password). If 1Password is locked, you'll also be prompted to unlock the app so the SSH agent can access your private keys. _[Authorization prompt showing a Touch ID icon.]_ _[Authorization prompt showing that the 1Password account password needs to be entered.]_ _[Authorization prompt showing a Windows Hello icon.]_ After approving the request, you can continue using the same SSH key for that application without being prompted again until 1Password locks or quits. You can also [configure your authorization settings](#adjust-your-authorization-options) to prompt more or less frequently. [Learn more about the 1Password SSH agent authorization model.](/docs/ssh/agent/security#authorization-model) ### Adjust your authorization options There are several options you can choose from to determine how long the agent remembers your SSH key approval and what usage you're approving for each key. These options determine when the SSH agent will ask you to approve SSH requests. #### In the 1Password settings Open 1Password, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**. In the security settings for the SSH agent, you can choose the options that best suit your needs. You can change your settings at any time. 1Password can ask you to approve an SSH request: - **For each new application** (default): You'll be asked to authorize SSH requests from each new application to use a specific SSH key. - **For each new application and terminal session**: Similar to the first option, you'll be asked to authorize SSH requests from each new application to use a specific SSH key. If the application is a terminal emulator or an IDE with a built-in terminal, you'll also be asked to authorize requests for each new terminal tab in that application. You can choose how long 1Password will remember your key approval. - **Until 1Password locks** (default): Every time 1Password locks, your key approvals are wiped from the agent's memory and you'll be asked to reauthorize any previously approved SSH clients to use your keys. For example, if you approve the terminal application to use your SSH key for GitHub, then 1Password locks, you'll need to reapprove any new requests from the terminal to use your GitHub SSH key when 1Password unlocks. [Learn how to change your 1Password lock settings.](https://support.1password.com/auto-lock/) - **Until 1Password quits**: Every time 1Password quits, your key approvals are wiped from the agent's memory. Any agent sessions and background processes will also end. To use the SSH agent to authorize any new requests to use your SSH keys, you'll need to reopen 1Password. - **For a set amount of time**: You can choose from 4, 12, or 24 hours. If you select one of these options, your key approvals will remain in the agent's memory for that duration, even when 1Password is locked. You won't need to reauthorize new requests from the same applications to use the same SSH keys you've already approved, but you'll be prompted to unlock 1Password so the SSH agent can access your private key. #### In the authorization prompt Every authorization prompt for a client to use an SSH key includes the option to approve the use of that key for all applications. To turn on this option, select the checkbox to **Approve for all applications**. This option can be selected for individual SSH keys. It temporarily authorizes all applications running in the current OS user account on your device to use that SSH key for the duration of the agent session (depending on [the options you've selected in the developer settings](#in-the-1password-settings) in 1Password). You can use this option alongside your other settings. [Learn more about the authorization options for the SSH agent.](/docs/ssh/agent/security#authorization-options) ## Learn more - [Manage SSH keys](/docs/ssh/manage-keys#generate-an-ssh-key) - [Autofill public keys](/docs/ssh/public-key-autofill/) - [SSH client compatibility](/docs/ssh/agent/compatibility/) - [Advanced use cases](/docs/ssh/agent/advanced/) - [About 1Password SSH Agent security](/docs/ssh/agent/security/) - [Use the 1Password SSH agent with WSL](/docs/ssh/integrations/wsl) --- ## Sign Git commits with SSH Git version 2.34 and later supports signing commits and tags with SSH keys — no GPG key needed. This means you can use the [1Password SSH integration](/docs/ssh/) to create new Git signing keys in seconds, and use them with your terminal apps and other [Git clients](/docs/ssh/agent/compatibility/) without the private key ever leaving 1Password. You can also automatically configure Git commit signing with SSH in the 1Password app. When you sign your commits, they can be cryptographically verified using the SSH public keys associated with your [GitHub ](https://docs.github.com/en/authentication/managing-commit-signature-verification/about-commit-signature-verification), [GitLab ](https://docs.gitlab.com/user/project/repository/signed_commits/ssh#configure-git-to-sign-commits-with-your-ssh-key), or [Bitbucket ](https://support.atlassian.com/bitbucket-cloud/docs/use-ssh-keys-to-sign-commits/) account. This ensures other people can verify that the changes were actually made by you. This is important because anyone with push rights to your repository can push new commits as any author, allowing them to impersonate others if commits aren't signed. [Learn how easy it is to use 1Password to sign your Git commits.](https://blog.1password.com/git-commit-signing/) ## Requirements Before you get started, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. Update to Git 2.34.0 or later. 4. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 5. [Set up the 1Password SSH Agent.](/docs/ssh/get-started#step-3-turn-on-the-1password-ssh-agent) ## Step 1: Configure Git commit signing with SSH To automatically configure Git commit signing with SSH globally: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Edit Automatically**. Or select Copy Snippet, then paste the snippet into your `~/.gitconfig` file manually. _[The Configure Git Commit Signing window showing options to edit your config file automatically or copy the configuration snippet manually.]_ You can also [configure SSH signing in a single repository](#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: - Set `gpg.format` to `ssh`. - Set `user.signingkey` to the public key you chose to sign commits with. - Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* - Set `gpg.ssh.program` to the SSH signer binary provided by 1Password, so you don't have to set `SSH_AUTH_SOCK` yourself. *(optional)* :::tip If you use WSL on a Windows machine, learn how to set up the [1Password WSL integration](/docs/ssh/integrations/wsl) to authenticate SSH and Git commands and [sign your Git commits within WSL](/docs/ssh/integrations/wsl#sign-git-commits-with-ssh). ::: ## Step 2: Register your public key Now that you've configured SSH commit signing locally, you'll need to register your public key so that others can verify the authenticity of your commits. **GitHub:** To allow GitHub to verify your commits, visit the [GitHub SSH key settings ](https://github.com/settings/ssh/new) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. Make sure you set the "Key type" to `Signing key` to allow your SSH key to be used for signing commits. _[The GitHub form to add a new SSH key, with signing key selected.]_ **GitLab:** To allow GitLab to verify your commits, visit the [GitLab SSH key settings ](https://gitlab.com/-/user_settings/ssh_keys) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. Make sure you set the "Usage type" to either `Authentication & Signing` or `Signing` to allow your SSH key to be used for signing commits. _[The GitLab form to add a new SSH key, with authentication and signing selected.]_ **Bitbucket:** To allow Bitbucket to verify your commits, visit the [Bitbucket SSH key settings ](https://bitbucket.org/account/settings/ssh-keys/) to register your SSH key for commit signing. You can use the 1Password browser extension to automatically fill in the public key and key title. _[The Bitbucket form to add a new SSH key.]_ **Locally:** To verify SSH signatures locally, you'll need to create an [allowed signers file ](https://www.man7.org/linux/man-pages/man1/ssh-keygen.1.html#ALLOWED_SIGNERS) and configure Git to use it. You can choose to configure this globally, for example: ```shell touch ~/.ssh/allowed_signers git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers ``` Or to tie it to a single repository, for example: ```shell touch .git/allowed_signers git config --local gpg.ssh.allowedSignersFile .git/allowed_signers ``` In the allowed signers file, add pairs of emails and public keys you'd like to trust: ```text title="allowed_signers" wendy@appleseed.com ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO ``` You can share this file with others and could even consider checking it into Git, similar to a `CODEOWNERS` file. ## Step 3: Commit and push your code Now that you're all set up, you can commit some code: ``` git commit -m "Signing my first commit with SSH" ``` You'll be prompted to authorize your SSH key the same way you unlock the 1Password app (for example, with Touch ID or Windows Hello). If you've chosen to use the same key to sign as you do to push and pull, you can now also push without requiring additional authorization: ``` git push ``` ## Step 4: Verify your commit signature **GitHub:** If you look at your commit history on GitHub, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A GitHub commit marked with the verified badge and showing the SSH public key used to sign.]_ **GitLab:** If you look at your commit history on GitLab, you should see the `Verified` badge show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A GitLab commit marked with the verified badge and showing the SSH public key used to sign.]_ **Bitbucket:** If you look at your commit history on Bitbucket, you should see a verified checkmark show up on your SSH-signed commits. If you select it, you can see the SSH key used to sign it. _[A Bitbucket commit marked with the verified badge and showing the SSH public key used to sign.]_ **Locally:** To verify commits locally, run the following command: ```shell git log --show-signature ``` ## Advanced configuration ### Configure commit signing in a single repository You can enable Git commit signing with SSH for specific repositories or directories instead of globally. To do this: 1. Open the SSH key you want to use in your 1Password desktop app. 2. Select > **Configure Commit Signing**. 3. In the next window, select **Copy Snippet**. 4. Paste the snippet in the repository's `/.git/config` file instead of the global `~/.gitconfig` file. ### Configure multiple commit signing setups If you want to configure multiple commit signing setups, you can use the `includeIf` directive in your `~/.gitconfig`. For example, to use an SSH commit signing setup with 1Password as your default configuration and a non-1Password GPG setup for the `/work/acme` subdirectory: ```toml title="~/.gitconfig" [user] name = Wendy Appleseed email = wendy@appleseed.com signingkey = ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO [commit] gpgsign = true [gpg] format = ssh [gpg "ssh"] program = /Applications/1Password.app/Contents/MacOS/op-ssh-sign [includeIf "gitdir:~/work/acme/"] path = ~/work/acme/.gitconfig ``` ```toml title="~/work/acme/.gitconfig" [user] email = wendy.appleseed@acme.com signingkey = 6A40D13BBB936F443084E8C9292E4F983136B860 [gpg] format = openpgp ``` In this example, every repository under `~/work/acme` will use the GPG configuration, while the SSH configuration will be used everywhere else. ### Configure commit signing in remote environments You can [set up SSH agent forwarding](/docs/ssh/agent/forwarding) to authenticate Git requests and sign commits in remote environments, like from a [cloud development environment](/docs/ssh/agent/forwarding#cde) or [remote workstation](/docs/ssh/agent/forwarding#remote-workstation). ## Get help If Git says that SSH is an unsupported format If you see the following error message, then your Git version may be outdated: ```text error: unsupported value for gpg.format: ssh ``` Support for SSH commit signing was added to Git in version **2.34**. Run this command to check your Git version: ```shell git --version ``` It's common for operating systems and Git GUI clients to ship with an outdated version of Git out of the box. To install a more up-to-date version, see the [Git install docs. ](https://git-scm.com/downloads) In the case of Git GUI clients, check the app preferences to see if they allow you to change the Git binary to a more up-to-date version. If your commits fail after you change your Git configuration If you see one of the following error messages, it's likely related to your `user.signingkey` value. Make sure that's set to a valid SSH public key. ```text fatal: failed to write commit object ``` ```text could not deserialize public key ``` ```text No such file or directory ``` If your `user.signingkey` is set correctly in your `~/.gitconfig` file, check the value at the repository level by running the following command from your repo's directory: ```shell git config user.signingkey ``` Example of a correct output: ```text ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO ``` If the signing key is not the SSH public key you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. If you see errors related to the allowed signers file If you see the following error message, make sure you've properly configured your [allowed signers file](#step-2-register-your-public-key): ```text error: gpg.ssh.allowedSignersFile needs to be configured and exist for ssh signature verification ``` This error should not block you from browsing your commit log - it just prevents you from locally verifying the commit authenticity. If your SSH-signed commit doesn't get verified by Git, GitHub, GitLab, and/or Bitbucket If you believe you've signed your commits through SSH but they're not showing up as verified, there are a few things that could be happening: #### Commit author email mismatch Commit signatures will only show up as verified if the registered public key matches the commit author email. Make sure it matches the email you've registered on [GitHub ](https://github.com/settings/emails), [GitLab ](https://gitlab.com/-/user_settings/profile), or [Bitbucket ](https://id.atlassian.com/manage-profile/profile-and-visibility) in your allowed signers file. :::info Case-sensitive email addresses If your signed commits are verified locally but aren't verified on GitLab.com or Bitbucket, check for any case mismatches in your email address. For example, if the email address in your GitLab or Bitbucket account is `wendy@appleseed.com` but your `~/.gitconfig` file uses `Wendy@appleseed.com`, your commits will show as unverified in those accounts. ::: If you have the correct email in your `~/.gitconfig`, check that the settings have correctly propagated down to the repository level as well. To validate this, run the following command from your repo's directory: ```shell git config user.email ``` If this is not the email you've configured in your `~/.gitconfig`, you may have a [local override](#local-git-overrides) in your repository. #### Misconfigured public key On GitHub, visit the [SSH key settings ](https://github.com/settings/keys) and check that the key you've locally configured as `user.signingkey` shows up under "Signing keys". On GitLab, visit the [SSH key settings ](https://gitlab.com/-/user_settings/ssh_keys) and check that the key you've locally configured as `user.signingkey` shows up under "Your SSH keys". On Bitbucket, visit the [SSH key settings ](https://bitbucket.org/account/settings/ssh-keys/) and check that the key you've locally configured as `user.signingkey` shows up under "SSH keys". For a local allowed signers file, make sure your public key is present and matches your email. #### Unsupported Git client Most Git clients support SSH commit signing out of the box, but there are [a few exceptions](/docs/ssh/agent/compatibility/). Even though you may have configured Git correctly, a Git client that doesn't support SSH commit signing will leave your commit unsigned. Make sure to also [check that you're on the latest version of your Git client](#get-help). #### Local Git overrides Even though you may have configured your `~/.gitconfig` well, make sure to also check that the settings have correctly propagated down to the repository level. To validate this, run the following command from your repo's directory: ```shell cat << EOF gpg.format: $(git config gpg.format) user.signingkey: $(git config user.signingkey) gpg.ssh.program: $(git config gpg.ssh.program) commit.gpgsign: $(git config commit.gpgsign) EOF ``` Example of a correct output: ```text gpg.format: ssh user.signingkey: ssh-ed25519 AAAAC3NzaC1IZDI1NTE5AAAAIFIUXAdv5sWOrfZFEPAW8liKjBW3sFxuaNITBWwtFKO gpg.ssh.program: /Applications/1Password.app/Contents/MacOS/op-ssh-sign commit.gpgsign: true ``` If this output does not match up with what you've configured in your `~/.gitconfig`, unset the local values: ```shell git config --local --unset gpg.format git config --local --unset user.signingkey git config --local --unset gpg.ssh.program git config --local --unset commit.gpgsign ``` If you still end up with the wrong value somewhere, you can check where it originates from using the `--show-origin` flag: ```shell cat << EOF gpg.format: $(git config --show-origin gpg.format) user.signingkey: $(git config --show-origin user.signingkey) gpg.ssh.program: $(git config --show-origin gpg.ssh.program) commit.gpgsign: $(git config --show-origin commit.gpgsign) EOF ``` --- ## Use the 1Password SSH agent with WSL The 1Password Windows Subsystem for Linux (WSL) integration allows you to authenticate SSH and Git commands and sign your Git commits within WSL using the 1Password SSH agent running on your Windows host. The 1Password integration supports both WSL 1 and WSL 2. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. [Install and sign in to 1Password for Windows](https://1password.com/downloads/windows). 3. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) 4. [Set up the 1Password SSH agent](/docs/ssh/get-started/) on your Windows host and make sure it's running. 5. [Install Windows Subsystem for Linux on Windows ](https://learn.microsoft.com/windows/wsl/install) with your preferred Linux distribution. To use [SSH Git commit signing with the 1Password WSL integration](#sign-git-commits-with-ssh), you'll also need: - Git 2.34.0 or later. - A 64-bit version of Windows 10 or later. Arm-powered Windows devices aren't supported. ## How the integration works With WSL, you can [run Windows tools from the command line ](https://learn.microsoft.com/windows/wsl/filesystems#run-windows-tools-from-linux), such as the Windows OpenSSH client (`ssh.exe`). The 1Password WSL integration leverages the [interoperability ](https://learn.microsoft.com/windows/wsl/filesystems#interoperability-between-windows-and-linux-commands) built into WSL to forward SSH requests to the 1Password SSH agent on Windows. Instead of forwarding SSH *agent* requests, like with standard OpenSSH agent forwarding, you can effectively forward the entire SSH request from WSL to the `ssh.exe` process running on Windows. The `ssh.exe` process then uses the 1Password SSH agent on your Windows host to authenticate the request. This also means that any [changes to your SSH configuration](/docs/ssh/agent/advanced) need to be made in your Windows `%USERPROFILE%/.ssh/config` file, rather than the file on your WSL instance. ## Forward an SSH request 1. Check if the 1Password SSH agent is running **on your Windows host** with the following command: ```powershell ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` If the agent is running, a list with one or more SSH keys will be returned. These are the SSH keys you stored in 1Password that are available to use with the agent for SSH requests. 2. Check if WSL is forwarding SSH requests successfully by running the following command **in your WSL instance**: ```shell ssh-add.exe -l #code-result 256 SHA256:2zmxMpLy5MeIx18pBUkumptKkKinlghygOvV6URe8QI Git Authentication Key (ED25519) ``` You should see the same list of SSH keys returned as you did when you ran the command on your Windows host. If you do, then WSL is forwarding your SSH requests to your Windows host.[Get help](#error-command-not-found) if you don't see your SSH key(s) listed when you run the `ssh-add.exe -l` command. 3. If you see your SSH key(s) listed in WSL, try to run an SSH request, replacing `ssh` with `ssh.exe` in your command. For example: ```shell ssh.exe -T git@github.com ``` You should see a prompt from 1Password to authorize the SSH request: _[SSH authorization prompt for WSL.]_ You can now use the 1Password SSH agent to forward SSH requests between your Windows host and WSL instance. ## Configure Git to use `ssh.exe` To use the 1Password SSH agent to authenticate Git commands in WSL, you can configure Git to use `ssh.exe` as the `core.sshCommand`. To set this variable globally, run the following command in WSL: ```shell git config --global core.sshCommand ssh.exe ``` ## Sign Git commits with SSH :::info 1Password for Windows 8.11.18 and later uses a new [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which automatically [updates the app data path](#error-cannot-run). If you set up the SSH agent to authenticate Git commands in WSL prior to version 8.11.18, you'll need to follow the steps below to configure Git commit signing again. ::: With Git configured to use `ssh.exe`, you can also use the integration to sign Git commits from WSL. To configure Git commit signing with SSH globally in WSL: 1. On your Windows host, open the 1Password app, then open the SSH key you want to use. 2. Select > **Configure Commit Signing**. 3. In the next window, select the checkbox to **Configure for Windows Subsystem for Linux (WSL)**, then select **Copy Snippet**. 4. In your WSL instance, paste the snippet into your `~/.gitconfig` file. _[The Configure Git Commit Signing window showing the checkbox to configure for WSL and the configuration snippet.]_ You can also [configure SSH signing in a single repository](/docs/ssh/git-commit-signing#configure-commit-signing-in-a-single-repository). 1Password will make the following changes to your Git config file: - Set `gpg.format` to `ssh`. - Set `user.signingkey` to the public key you chose to sign commits with. - Set `commit.gpgsign` to `true` so you don't need to include the `-S` flag with each commit. *(optional)* - Set `gpg.ssh.program` to the SSH signer binary provided by 1Password. After you set up Git commit signing on WSL, you can use the same steps as your Windows host to test the configuration. [Register your public key](/docs/ssh/git-commit-signing#step-2-register-your-public-key), then [commit some code](/docs/ssh/git-commit-signing#step-3-commit-and-push-your-code) and [verify your commit is signed](/docs/ssh/git-commit-signing#step-4-verify-your-commit-signature). ## Optional: Add an alias for SSH commands If you plan to use the 1Password SSH agent on your Windows host to authenticate SSH requests other than Git, you can optionally [create aliases in your Bash profile ](https://linux.die.net/Bash-Beginners-Guide/sect_03_05.html) to use `ssh` and `ssh-add` on the command line in place of `ssh.exe` and `ssh-add.exe`. This isn't required, but it can be convenient to use the same SSH commands across all your platforms. In your `~/.bashrc` or `~/.bash_aliases` file, add the following aliases: ```shell alias ssh='ssh.exe' alias ssh-add='ssh-add.exe' ``` ## Authorization model The 1Password SSH agent uses the same [authorization model](/docs/ssh/agent/security#authorization-model) with the WSL integration as it does on other platforms. When you approve an SSH key request for a WSL session, only the current session is authorized to use that key. If you open a new WSL session or tab, you'll be prompted to approve the SSH request again. [Learn more about the 1Password SSH agent authorization model.](/docs/ssh/agent/security#authorization-model) ## Troubleshooting ### Error: `command not found` If you see a `command not found` error when you run the `ssh-add.exe -l` command in WSL, OpenSSH may not be in your `PATH`. Try to run the command again using the full executable path: ```shell /mnt/c/Windows/System32/OpenSSH/ssh-add.exe -l ``` If you still see an error, check if the [interoperability setting ](https://learn.microsoft.com/windows/wsl/wsl-config#interop-settings) (`[interop]`)is turned on in your WSL config file. If it is, the entry will look like this: ```text [interop] enabled = true ``` If you see `enabled = false` instead, set the `enabled` value to `true`. ### Error: `cannot run` 1Password for Windows 8.11.18 and later uses an [MSIX installer](https://support.1password.com/cs/1password-msix-installer/), which updates the app data path previously used by the EXE installer. If you configured the SSH agent to authenticate Git commands in WSL using an earlier version of the app, you may see the following error message: ``` fatal: cannot run /mnt/c/Users//AppData/Local/1Password/app/8/op-ssh-sign-wsl: No such file or directory ``` To fix the issue, you'll need to [reconfigure Git commit signing for WSL](#sign-git-commits-with-ssh). This will add the updated path to your `.gitconfig` file. ```text title="Deprecated path (8.11.16 and earlier)" /mnt/c/Users//AppData/Local/1Password/app/8/op-ssh-sign-wsl ``` ```text title="New path (8.11.18 and later)" /mnt/c/Users//AppData/Local/Microsoft/WindowsApps/op-ssh-sign-wsl.exe ``` --- ## Manage SSH keys You can use 1Password to manage all your SSH keys. [Generate SSH Key items](#generate-an-ssh-key) – with public keys, fingerprints, and private keys – right in 1Password. And if you have existing SSH keys, you can [import them into 1Password](#import-an-ssh-key). You can also [export your SSH keys](#export-an-ssh-key) from 1Password at any time. :::tip If you manage multiple SSH keys and you want to use them with the [1Password SSH Agent](/docs/ssh/agent/), learn more about how to avoid the [SSH server six-key limit](/docs/ssh/agent/advanced#ssh-server-six-key-limit). ::: ## Requirements Before you can use 1Password to manage your SSH keys, you'll need to: 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. (Optional) [Install 1Password CLI](/docs/cli/get-started#step-1-install-1password-cli) `2.20.0` or later. Required to create SSH keys using 1Password CLI. ## Generate an SSH key Generate an SSH key in the 1Password desktop apps or with 1Password CLI to use anywhere you need one. **Desktop apps:** 1. Open and unlock the 1Password app, then navigate to your [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault in the sidebar. If you've configured the SSH agent for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. 2. Select **New Item**, then select **SSH Key**. 3. Select **Add Private Key** > **Generate a New Key**. 4. Choose a [key type](#supported-ssh-key-types), then select **Generate**. 5. You can edit the name of your key and make any other changes. When you're done, select **Save**. _[The 1Password save dialog for an SSH Key item with the option to generate an Ed25519 key type selected.]_ **1Password CLI:** 1. Open the terminal and [sign in](/docs/cli/get-started#step-3-enter-any-command-to-sign-in) to your 1Password account. 2. To generate an SSH key, run: ```shell op item create --category ssh --title "My SSH Key" ``` 1Password CLI will generate an [Ed25519](#ed25519) key by default. Learn how to [create an RSA key](/docs/cli/ssh-keys#generate-an-ssh-key) instead. 3. After you run the command, 1Password CLI will generate an SSH key and save it as a new item in your built-in [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault, then will print the key to stdout with the private key redacted. SSH keys are saved in your Personal, Private, or Employee vault by default. See the full [1Password CLI documentation](/docs/cli/ssh-keys/) for more information about how to manage your SSH keys on the command line. ## Import an SSH key {#import-an-ssh-key} If you have an SSH key you want to save in 1Password, you can import it. 1. Open and unlock the 1Password desktop app, then navigate to your [Personal](https://support.1password.com/1password-glossary#personal-vault), [Private](https://support.1password.com/1password-glossary#private-vault), or [Employee](https://support.1password.com/1password-glossary#employee-vault) vault in the sidebar. If you've configured the SSH agent for any shared or custom vaults, you can generate your SSH key in one of those vaults instead. 2. Select **New Item** > **SSH Key**. 3. Select **Add Private Key** > **Import a Key File**, then navigate to the location of the SSH key you want and select **Import**. You can also drag and drop your SSH key file directly into the new SSH item or paste it from your clipboard. 4. If your SSH key is encrypted with a passphrase, enter the passphrase and select **Decrypt**. You'll only need to enter the passphrase once. After you import the SSH key into 1Password, it'll be encrypted according to the [1Password security model](https://support.1password.com/1password-security#encryption). 5. When you're done, select **Save**. _[A new SSH Key item with Import a Key File selected.]_ :::tip Is your passphrase saved in 1Password? If the passphrase for your SSH key is already saved in 1Password, use Quick Access to find and copy it without needing to switch context. ::: ### Key import errors If you see one of the error messages below when you import an SSH key in 1Password, check if there's an issue with the type of key, the file format, or the encryption:
**If you see a message that your SSH key isn't supported** If you see a message that your SSH key isn't supported, make sure you're importing a [supported Ed25519 or RSA (2048, 3072, or 4096-bit) key](/docs/ssh/manage-keys#supported-ssh-key-types). Other key lengths and other key types, such as **DSA** or **ECDSA** keys, aren't supported. To check the key type and bit length, run the following command: ```shell ssh-keygen -l -f ``` RSA keys also require a minimum public exponent of **65,537** to meet [NIST standards](https://csrc.nist.rip/library/NIST%20SP%20800-078-2%20Cryptographic%20Algorithms%20and%20Key%20Sizes%20for%20Personal%20Identification%20Verification%20(PIV),%202010-02.pdf). RSA keys with a public exponent less than 65,537 aren't supported. To check the size of the public exponent for your key, run the following command: ```shell openssl rsa -text -in | grep publicExponent ```
**If you see a message that your SSH key file couldn't be read** If you see a message that your SSH key file couldn't be read, make sure the key file is in a supported format. 1Password supports **PKCS#1**, **PKCS#8**, and **OpenSSH** formats. Keys that use a different file format, such as PuTTYgen `.ppk`, aren't supported.
**If you see a message that your SSH key couldn't be decrypted** If you see a message that your SSH key couldn't be decrypted, it could be that it's encrypted with an unsupported and outdated cipher such as **RC4**. You can re-encrypt your key file so that it uses a more modern algorithm and then try importing it again. To do this, run the following command: ```shell ssh-keygen -p -f path/to/your/key ``` If you still can't import your SSH key, you can use 1Password to [generate a new SSH key](/docs/ssh/manage-keys#generate-an-ssh-key) using the latest standards. ## Export an SSH key You can export a private SSH key from 1Password at any time. 1. Open and unlock the 1Password desktop app. 2. Choose the SSH key you want to export, then select the private key field. 3. Choose the export format you need: **OpenSSH** or **PKCS#8**. If you imported a PKCS#1-formatted key into 1Password, you will also have the option to export that key in **PKCS#1** format. 4. Choose how you want to export your private key: - To encrypt your exported private key (OpenSSH format only), enter a passphrase, then select **Copy Encrypted Key** or **Download Encrypted Key**. - To export your private key in plaintext, leave the passphrase field empty (if there is one), then select **Copy Unencrypted Key** or **Download Unencrypted Key**. _[A GitHub SSH key item with the private key field highlighted to show the Export option.]_ _[The export dialog for a private key with an empty passphrase field and copy and download buttons.]_ :::warning[Keep your private keys safe] 1Password can't protect SSH keys that you store outside of your account. If you need to export a private key, we recommend you save it in a secure location. Don't store unencrypted private keys on disk. ::: ## Share a public key {#share-a-public-key} 1Password will automatically generate the public key and fingerprint for each private key you create so you can share it with the services and people who need it. You can copy or download the public key of an SSH key in the right format every time, and you can use the fingerprint to compare and identify your keys across all your services. For platforms that let you provide public keys in the browser (often found in an SSH Key settings panel), you can use 1Password in your browser to [fill your public key](/docs/ssh/public-key-autofill/). You can also copy your public key from the item view in 1Password and share it where needed, or use [Quick Access](https://support.1password.com/quick-access/) to find your public key even faster without needing to switch context. _[Copy or download your public key to share it with others.]_ ## Supported SSH key types 1Password supports the following key types, formats, and encryption algorithms: - **Key types**: [Ed25519](#ed25519) and [RSA](#rsa) (2048, 3072, and 4096-bit) - **Formats**: PKCS#1, PKCS#8, and OpenSSH - **Encryption**: AES and 3DES (all supported key formats), and ChaCha20-Poly1305 (OpenSSH format only) ### Ed25519 Ed25519 is the fastest and most secure key type available today and is the option recommended by most Git and cloud platforms. Ed25519 is the default suggestion when you generate a new SSH key in 1Password and the key is automatically set to 256 bits. The Ed25519 key type was first introduced in 2014 with [OpenSSH 6.5](https://www.openssh.com/releasenotes.html). If you need to connect to an older server that isn't using OpenSSH 6.5 or later, an Ed25519 key won't work. ### RSA RSA is one of the oldest key types available and is compatible with most servers, including older ones. Compared to Ed25519, RSA is considerably slower, particularly with decryption, and is only considered secure if it's 2048 bits or longer. 1Password supports 2048-bit, 3072-bit, and 4096-bit RSA keys. ## View SSH keys in 1Password 7 Generating, importing, and sharing SSH keys requires 1Password 8. Any SSH keys that you generate or import can be viewed and copied in the 1Password 7 apps on your other devices. Make sure you're using an [updated version](https://support.1password.com/update-1password/) of 1Password 7 to view or copy your public or private keys. --- ## 1Password for SSH & Git Introducing 1Password for SSH & Git, the single source of truth for all your SSH keys. With 1Password, you can: - [Generate and import](/docs/ssh/manage-keys/) your SSH keys. - [Autofill public keys](/docs/ssh/public-key-autofill/) in your browser for Git and other cloud platforms. - Automatically configure [Git commit signing with SSH](/docs/ssh/git-commit-signing/) from the 1Password app. - Use the [1Password SSH Agent](/docs/ssh/agent/) to authenticate all your Git and SSH workflows. _[A terminal with a git push command, overlaid with a 1Password authorization prompt to approve the request to use an SSH key.]_ The SSH agent works with your existing SSH clients and acts as their key provider. Use your keys in your SSH workflows, like when you work with Git to check code into source control, or when you log in to virtual machines. 1Password stores all your SSH keys behind secure end-to-end encryption, allowing you to access your keys when you need them without your SSH keys ever leaving 1Password. ## Quick start ### [Get started](/docs/ssh/get-started/) If you're setting up SSH in 1Password for the first time, start here. ## Guides ### [Manage SSH keys](/docs/ssh/manage-keys/) Learn how to generate and import SSH keys, and how to copy or download your public key if you need to share it. ### [Autofill public keys](/docs/ssh/public-key-autofill/) Learn how to use 1Password in your browser to fill your public keys on your favourite Git or cloud platforms. ### [Sign Git commits with SSH](/docs/ssh/git-commit-signing/) Learn how to automatically configure Git commit signing with SSH through the 1Password app. ### [Advanced use cases](/docs/ssh/agent/advanced/) Learn how to configure the 1Password SSH agent for specific hosts and how to avoid rate limits with OpenSSH servers. ### [1Password agent config file](/docs/ssh/agent/config/) Learn how to create and customize an SSH agent config file if you need to use SSH keys from shared or custom vaults or have more fine-grained control over the behavior of the SSH agent. ## Reference documentation ### [SSH client compatibility](/docs/ssh/agent/compatibility/) Learn which SSH and Git clients have been tested with the 1Password SSH agent. ### [About 1Password SSH Agent security](/docs/ssh/agent/security/) Learn about the authorization model for the 1Password SSH agent, how it's different from the OpenSSH agent, and what's kept in local storage. --- ## Autofill public keys To use the SSH keys you saved in 1Password to connect to your favorite Git or cloud platforms, you'll need to provide your public key to those services. [Use 1Password in your browser](https://support.1password.com/getting-started-browser/) to fill your public key on those sites, anywhere you see the 1Password icon. Or copy your public key from the SSH key item in 1Password and paste it into the public key area of the website. ## Requirements 1. [Sign up for 1Password.](https://1password.com/pricing/password-manager) 2. Install and sign in to 1Password for [Mac](https://1password.com/downloads/mac), [Windows](https://1password.com/downloads/windows), or [Linux](https://1password.com/downloads/linux). 3. [Install the 1Password browser extension.](https://1password.com/downloads/browser-extension) 4. [Import or generate SSH keys in 1Password.](/docs/ssh/manage-keys/) ## AWS CodeCommit Visit the **Security credentials** tab of your [IAM user](https://console.aws.amazon.com/iam/home#/users) to add a new key: ## Azure DevOps Visit the **SSH public keys** page of your user settings to add a new key: ## Bitbucket Visit the [Bitbucket SSH key settings](https://bitbucket.org/account/settings/ssh-keys/) to add a new key: It also works for [access keys](https://support.atlassian.com/bitbucket-cloud/docs/add-access-keys/). ## DigitalOcean Visit your [account security settings](https://cloud.digitalocean.com/account/security) to add a new key: ## GitHub Visit the [GitHub SSH key settings](https://github.com/settings/ssh/new) to add a new key: You can also autofill [deploy keys](https://docs.github.com/en/developers/overview/managing-deploy-keys#deploy-keys). ## GitLab Visit the [GitLab SSH key settings](https://gitlab.com/-/user_settings/ssh_keys) to add a new key: It also works for [deploy keys](https://docs.gitlab.com/user/project/deploy_keys/). ## Gitpod Visit the [Gitpod SSH key settings](https://gitpod.io/keys) to add a new key: ## Google Compute Engine Visit the [Google Compute Engine metadata settings](https://console.cloud.google.com/compute/metadata?tab=sshkeys) to add a new key: ## IBM Cloud (VPC) Visit the [**SSH keys** section](https://cloud.ibm.com/vpc-ext/compute/sshKeys) in the VPC Infrastructure console to add a new key: ## IBM Cloud (Classic) Visit the [**SSH keys** section](https://cloud.ibm.com/gen1/infrastructure/ssh-keys) in the Classic Infrastructure console to add a new key: ## JetBrains Space Visit the **Git Keys** tab in your Space profile settings to add a new key: ## Linode Visit the [**SSH Keys** section in your profile](https://cloud.linode.com/profile/keys) to add a new key: ## Microsoft Azure Visit the [**SSH keys** section in the Azure portal](https://portal.azure.com#create/Microsoft.SshKey) to add a new key: ## Ngrok Visit the [**SSH Public Keys** section in the Ngrok dashboard](https://dashboard.ngrok.com/tunnels/ssh-keys/new) to add a new key: ## Vultr Visit the [Vultr SSH key settings](https://my.vultr.com/settings#settingssshkeys) to add a new key: