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

# Get started with 1Password for SSH

export const YouTubeVideo = ({src, title, alt}) => {
  return <Frame>
      <iframe className="w-full aspect-video rounded-xl" src={src} title={alt ?? title} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>
    </Frame>;
};

export const Image = ({src, darkSrc, alt, width, border, height, round}) => {
  const classNames = ["mint-mx-4"];
  if (border) {
    classNames.push("mint-rounded-sm");
  }
  if (round) {
    classNames.push("mint-rounded-lg");
  }
  const style = {};
  if (width) style.width = typeof width === "number" ? `${width}px` : width;
  if (height) style.height = typeof height === "number" ? `${height}px` : height;
  return darkSrc ? <>
      <img src={src} alt={alt} className={[...classNames, "dark:hidden"].join(" ")} style={Object.keys(style).length > 0 ? style : undefined} />
      <img src={darkSrc} alt={alt} className={[...classNames, "hidden dark:block"].join(" ")} style={Object.keys(style).length > 0 ? style : undefined} onError={e => {
    e.target.src = src;
  }} />
    </> : <img src={src} alt={alt} className={classNames.join(" ")} style={Object.keys(style).length > 0 ? style : undefined} />;
};

export const Small = ({children}) => {
  return <small>{children}</small>;
};

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.

<YouTubeVideo src="https://www.youtube.com/embed/X3-TNJTJBWE" alt="Video walkthrough that covers creating an SSH key, turning on the 1Password SSH agent, authenticating to GitHub with Touch ID, and signing Git commits." />

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

<Tabs groupId="operating-systems">
  <Tab title="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).<br />
       <Small>Required to autofill SSH keys in your browser.</Small>
  </Tab>

  <Tab title="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).<br />
       <Small>Required to autofill SSH keys in your browser.</Small>
  </Tab>

  <Tab title="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).<br />
       <Small>Required to autofill SSH keys in your browser.</Small>

    <Warning>
      The 1Password SSH agent doesn't work with [Flatpak <Icon icon="arrow-up-right-from-square" />](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/).
    </Warning>
  </Tab>
</Tabs>

<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.
</Tip>

## Step 1: Generate an SSH key

<CardGroup cols={2}>
  <div>
    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](/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.
  </div>

  <div>
    <Image border round alt="Generating a new SSH Key item with the Ed25519 key type selected." width="300" src="/static/img/ssh/github-generate-ssh-key.png" />
  </div>
</CardGroup>

Learn more about [generating or importing SSH keys](/ssh/manage-keys/) and [which SSH keys you can use with the 1Password SSH agent](/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.

<Tabs>
  <Tab title="Browser extension">
    <CardGroup cols={2}>
      <div>
        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.

        <p>Your SSH key can now be used to authenticate with GitHub.</p>

        <p>For examples using other Git or cloud platforms, see [Autofill public keys](/ssh/public-key-autofill/).</p>
      </div>

      <div>
        <Image border round alt="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." width="300" src="/static/img/ssh/add-public-key-github.png" />
      </div>
    </CardGroup>
  </Tab>

  <Tab title="Desktop apps">
    <CardGroup cols={2}>
      <div>
        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.<br /> <Small>You can also use <a href="https://support.1password.com/quick-access/">Quick Access</a> to find and copy your public key.</Small>
        3. Then select **Add SSH Key** on the settings page to save the key in your GitHub account.

        <p>Your SSH key can now be used to authenticate with GitHub.</p>

        <p>For examples using other Git or cloud platforms, see [Autofill public keys](/ssh/public-key-autofill/).</p>
      </div>

      <div>
        <Image border round alt="A GitHub SSH Key item selected in the 1Password desktop app, with the public key field selected and ready to copy." width="300" src="/static/img/ssh/copy-public-key-github.png" />
      </div>
    </CardGroup>
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Mac">
    <CardGroup cols={2}>
      <div>
        1. Open the 1Password app and select **1Password** > **Settings** from the menu bar, then select **Developer**.
        2. Select **Use the 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.
      </div>

      <div>
        <Image border round alt="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." src="/static/img/ssh/turn-on-ssh-agent.png" />
      </div>
    </CardGroup>

    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](/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:

    <CardGroup cols={2}>
      <div>
        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**.
      </div>

      <div>
        <Image border round alt="The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running." src="/static/img/ssh/keep-1password-running-mac.png" />
      </div>
    </CardGroup>
  </Tab>

  <Tab title="Windows">
    <Warning>
      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](/ssh/agent/compatibility/).
    </Warning>

    #### 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 <kbd>Win</kbd> + <kbd>R</kbd> on your keyboard to open the Run window, type `services.msc` and press <kbd>Enter</kbd> 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](/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 <kbd>Enter</kbd>.
    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`.

    #### Turn on the SSH agent in 1Password

    Follow these steps to turn on the SSH agent in 1Password:

    <CardGroup cols={2}>
      <div>
        1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**.
        2. Select **Use the 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.
      </div>

      <div>
        <Image border round alt="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." src="/static/img/ssh/turn-on-ssh-agent.png" />
      </div>
    </CardGroup>

    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](/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:

    <CardGroup cols={2}>
      <div>
        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**.
      </div>

      <div>
        <Image border round alt="The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running." src="/static/img/ssh/keep-1password-running-mac.png" />
      </div>
    </CardGroup>
  </Tab>

  <Tab title="Linux">
    <CardGroup cols={2}>
      <div>
        1. Open the 1Password app, then select your account or collection at the top of the sidebar and select **Settings** > **Developer**.
        2. Select **Use the 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.
      </div>

      <div>
        <Image border round alt="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." src="/static/img/ssh/turn-on-ssh-agent.png" />
      </div>
    </CardGroup>

    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](/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:

    <CardGroup cols={2}>
      <div>
        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**.
      </div>

      <div>
        <Image border round alt="The general settings page in the 1Password desktop app, with the checkboxes selected for the settings to keep the SSH agent running." src="/static/img/ssh/keep-1password-running-mac.png" />
      </div>
    </CardGroup>
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Mac">
    Add the `IdentityAgent` snippet to your `~/.ssh/config` file:

    ```text theme={null}
    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 theme={null}
    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 theme={null}
    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](/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](/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](/ssh/agent/advanced/#ssh-server-six-key-limit).
  </Tab>

  <Tab title="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:

    ```text theme={null}
    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):

    ```text theme={null}
    [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](/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](/ssh/agent/advanced/#ssh-server-six-key-limit).
  </Tab>

  <Tab title="Linux">
    Add the `IdentityAgent` snippet to your `~/.ssh/config` file:

    ```text theme={null}
    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 theme={null}
    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](/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](/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](/ssh/agent/advanced/#ssh-server-six-key-limit).
  </Tab>
</Tabs>

## Step 5: Run a command

Now you're ready to start using the 1Password SSH agent with GitHub.

From your project directory, run:

```text theme={null}
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:

```text theme={null}
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.

<CardGroup cols={3}>
  <div>
    <Image alt="Authorization prompt showing a Touch ID icon." src="/static/img/ssh/auth-prompt-touch-id.png" />
  </div>

  <div>
    <Image alt="Authorization prompt showing that the 1Password account password needs to be entered." src="/static/img/ssh/auth-prompt-account-password.png" />
  </div>

  <div>
    <Image alt="Authorization prompt showing a Windows Hello icon." src="/static/img/ssh/auth-prompt-windows-hello.png" />
  </div>
</CardGroup>

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.](/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.

<div style={{ textAlign: "center" }}>
  <img alt="SSH agent security settings showing the menu with the two options for when 1Password will ask you to approve SSH requests." width="65%" src="https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/security-settings-ask-approval.png?fit=max&auto=format&n=2GuQWN9fVwUxVlhr&q=85&s=cdb54e48ed0ab9ebef6b38f32caaba07" data-path="static/img/ssh/security-settings-ask-approval.png" />
</div>

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.

<div style={{ textAlign: "center" }}>
  <img alt="SSH agent security settings showing the menu with the options for how long 1Password remembers your key approval." width="65%" src="https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/security-settings-remember-approval.png?fit=max&auto=format&n=2GuQWN9fVwUxVlhr&q=85&s=ff7a283644d16f69a7ea3c0db7920535" data-path="static/img/ssh/security-settings-remember-approval.png" />
</div>

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

<div style={{ textAlign: "center" }}>
  <img alt="An authorization prompt from 1Password with the allow all option checked, showing that all applications can use the GitHub SSH key." width="45%" src="https://mintcdn.com/ab-634991b8/2GuQWN9fVwUxVlhr/static/img/ssh/auth-prompt-allow-all.png?fit=max&auto=format&n=2GuQWN9fVwUxVlhr&q=85&s=88b825036eeee9398662ca7b226167e6" data-path="static/img/ssh/auth-prompt-allow-all.png" />
</div>

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.](/ssh/agent/security/#authorization-options)

## Learn more

* [Manage SSH keys](/ssh/manage-keys/#generate-an-ssh-key)
* [Autofill public keys](/ssh/public-key-autofill/)
* [SSH client compatibility](/ssh/agent/compatibility/)
* [Advanced use cases](/ssh/agent/advanced/)
* [About 1Password SSH Agent security](/ssh/agent/security/)
* [Use the 1Password SSH agent with WSL](/ssh/integrations/wsl)