---
title: SSH agent
description: Sign SSH requests with keys from your vault, from desktop tools,
  Termux and Android apps.
url: https://keyguard.dev/docs/ssh-agent/
platforms:
  - android
  - linux
  - macos
  - windows
premium: false
---

# SSH agent

Keyguard can act as an SSH agent for OpenSSH clients such as `ssh` and `git`. The private key never leaves your vault: a client sends Keyguard the data to sign and gets back only the signature. No key file sits on disk for other programs to read or copy.

Keyguard asks you to approve requests and logs every request. [Agent approvals](https://keyguard.dev/docs/agent-approvals/) covers when Keyguard remembers an approval.

### Before you begin

- An **SSH Key** item in your vault, holding an Ed25519 or RSA key. The [Generator](https://keyguard.dev/docs/generator/) creates one, and Keyguard imports OpenSSH and PEM keys, with or without a passphrase.
- **SSH agent** turned on in **Settings > Developer > SSH agent**.

## Set up the agent on desktop

Open **Settings > Developer > SSH agent > SSH client setup**. Under **Automatic configuration**, select **Configure automatically**. Choose all SSH hosts or one host or alias, and optionally select your shells. Continue to review the file changes, then select **Apply changes**. The wizard checks the agent connection after applying. Open a new terminal and test remote authentication with your chosen key.

The Flatpak build can’t edit host files, so the wizard shows a command instead. Run it in a host terminal. It shows the file changes and asks before applying them.

Setup supports Bash, Zsh, Fish, PowerShell 7 and Windows PowerShell 5.1. It adds Keyguard’s settings to the end of each file and leaves your lines unchanged. For [Pin hosts to keys](https://keyguard.dev/docs/ssh-agent/#pin-hosts-to-keys), it also adds an `Include` line to the top of `~/.ssh/config`.

**Check these lines** lists lines that can take precedence over Keyguard’s settings. These are `SSH_AUTH_SOCK` lines that run later, and `IdentityAgent` lines earlier in `~/.ssh/config`. Make sure they don’t select another agent.

If no files need changes, select **Check agent connection**. This tests Keyguard’s endpoint; it does not prove which settings your shell loads.

Setup stops for symlinked files, or for a compiled Zsh startup file (`.zwc`) dated in the future. Resolve these manually, then review again.

The undo icon in **Automatic configuration** opens a review of recorded settings to remove. Undo preserves other edits and does not stop agents or change the Windows OpenSSH service.

For manual setup:

1. Add this line to your shell profile, with your platform’s path from [Endpoints](https://keyguard.dev/docs/ssh-agent/#endpoints):

   ```sh
   export SSH_AUTH_SOCK="<ENDPOINT>"
   ```

   On Windows, add this line to your PowerShell profile:

   ```powershell
   $env:SSH_AUTH_SOCK="\\.\pipe\keyguard-ssh-agent"
   ```

2. Open a new shell.

3. Run `ssh-add -L`. It lists the public keys that Keyguard serves.

Instead of `SSH_AUTH_SOCK`, you can set `IdentityAgent` in `~/.ssh/config`. In this file, write environment variables in braces, such as `${HOME}`. On macOS:

```plaintext
Host *
  IdentityAgent "${HOME}/.keyguard/ssh-agent.sock"
```

On Windows, use forward slashes in the SSH configuration:

```plaintext
Host *
  IdentityAgent "//./pipe/keyguard-ssh-agent"
```

`ssh-add` reads `SSH_AUTH_SOCK`, not `IdentityAgent`. Select a terminal environment or set the variable explicitly before using `ssh-add -L`.

## Set up the agent in Termux

Termux reaches Keyguard through a helper package.

1. Install [Termux](https://termux.dev/).

2. In Keyguard, open **Settings > Developer > SSH agent > SSH client setup**.

3. In Termux, run the commands under **Install package**. They add Keyguard’s APT repository and install `openssh` and `keyguard-android-ssh-agent`.

4. Review and apply startup configuration for your shell:

   ```sh
   keyguard-android-ssh-agent --setup-shells bash
   ```

   Choose `bash`, `zsh`, `fish`, or a comma-separated list. The helper asks before editing files. To review removal, run `keyguard-android-ssh-agent --undo-setup`.

5. Open a new Termux session.

6. Run `ssh-add -L`. It lists the public keys that Keyguard serves.

When `ssh` uses a key, Keyguard asks for your approval.

## Use the agent from other Android apps

Apps that support the OpenKeychain SSH Authentication API use Keyguard directly, without Termux. They see Keyguard only while **SSH agent** is on.

1. In the other app, select **Keyguard** as the SSH key provider. The setting’s name depends on the app.
2. In Keyguard, approve the registration request.

Later requests can ask you to choose a key, unlock the vault or authenticate. To revoke an app, select it in **Settings > Developer > Connected apps**, then select **Revoke**.

## Sign in with a certificate

An OpenSSH certificate is your public key signed by a certificate authority. A server that trusts the authority accepts it without your key in `authorized_keys`.

1. Edit the **SSH Key** item.
2. Paste the contents of the key’s `-cert.pub` file into **Certificate**, or drop the file on the key.
3. Save the item.

The agent offers the certificate before the key while the certificate is valid. The item shows why a certificate isn’t offered: it expired, isn’t valid yet, is a host certificate or is for another key. Apps that use the OpenKeychain API get the key only.

Keyguard doesn’t renew certificates. To use one that your certificate authority renews often, keep it on disk and point `CertificateFile` at it:

```plaintext
Host <HOST>
  CertificateFile ~/.ssh/<KEY_NAME>-cert.pub
```

## Pin hosts to keys

The agent offers every key to every host. A server that allows few attempts can stop with “Too many authentication failures” before it gets the right key. A pinned host gets only its own keys.

1. Edit the **SSH Key** item and add a host, such as `git@github.com`, under **SSH bookmarks**. [Custom field conventions](https://keyguard.dev/docs/item-extras/#ssh-bookmarks) lists the format.
2. In **Settings > Developer > SSH agent**, turn on **Generate SSH config for bookmarked hosts**. If `~/.ssh/config` doesn’t include the generated config, the setting stays off. Select **Run SSH client setup**, or add the line below yourself. Then turn the setting on again.

The Flatpak build can’t read `~/.ssh/config`, so the setting turns on without this check. Then follow [Set up the agent on desktop](https://keyguard.dev/docs/ssh-agent/#set-up-the-agent-on-desktop) again.

For manual setup, add this line to the top of `~/.ssh/config`, with your platform’s directory:

```plaintext
Include "<DIRECTORY>/config"
```

| Platform | Directory |
| - | - |
| Linux, macOS, Windows | `~/.ssh/keyguard` |
| Linux, Flatpak | `~/.var/app/com.artemchep.keyguard/data/ssh-bookmarks` |

Keyguard keeps a `Match host` block for each bookmarked host in that file, plus the public keys and certificates it names. It updates them while the vault is unlocked, and deletes them when you turn the setting off. The host names and public keys are not encrypted.

`ssh` matches only the user and host on its command line. A bookmark for `git@github.com` doesn’t apply to `ssh github.com` with `User git` set later in `~/.ssh/config`. A pinned host doesn’t get the default keys from `~/.ssh`, so its key login fails while Keyguard isn’t running.

## Review request history

In **Settings > Developer > SSH agent**, select **Request log**. Each entry shows the caller, the key, the request and its result, such as **Success**, **Denied** or **Key not found**.

To see the requests for one key, open its **SSH Key** item and select **View SSH agent history**.

## Endpoints

| Platform | Endpoint |
| - | - |
| Android, Termux | `$PREFIX/tmp/keyguard-ssh-agent.sock` |
| Linux | `$XDG_RUNTIME_DIR/keyguard-ssh-agent.sock` |
| Linux, Flatpak | `$XDG_RUNTIME_DIR/app/com.artemchep.keyguard/ssh-agent.sock` |
| macOS | `$HOME/.keyguard/ssh-agent.sock` |
| Windows | `\\.\pipe\keyguard-ssh-agent` |

## Related

- [Agent approvals](https://keyguard.dev/docs/agent-approvals/)
- [Sign Git commits](https://keyguard.dev/docs/git-signing/)
- [GPG agent](https://keyguard.dev/docs/gpg-agent/)
- [Generator](https://keyguard.dev/docs/generator/)