What is an SSH Agent?

#

ssh-agent is a program to hold private keys used for public key authentication. Through use of environment variables the agent can be located and automatically used for authentication when logging in to other machines using ssh.¹

In practice, this means you can add your SSH private keys to the agent, which then handles authentication for you. This is convenient, but managing SSH keys across multiple systems can become cumbersome.

You either end up copying private keys to every machine, risking exposure if one system is compromised, or generating unique keys for each host, which complicates access control and creates management overhead.

Why Use Proton Pass as Your SSH Agent?

#

Proton Pass solves these problems by centralizing your SSH key management. Storing SSH keys in Proton Pass addresses these challenges:

• Centralizing access: Your keys are stored in an encrypted vault, accessible from any device with Proton Pass CLI installed.
• Maintaining security: Proton Pass uses end-to-end encryption, ensuring only you can decrypt and use your keys.
• Simplifying workflows: The Proton Pass CLI can act as an SSH agent or load your stored keys into your existing agent, eliminating the need for manual key management.

As the Proton Pass CLI documentation states:

The Proton Pass CLI integrates nicely with any existing SSH workflows. It can either act as a SSH agent, or load your Pass-stored SSH keys into your already existing SSH agent.²

Prerequisites

#

To manage your SSH keys with Proton Pass, you’ll need:

• A Proton Pass account
• The Proton Pass CLI installed on your system.

SSH Key Management

#

SSH keys can be added to Proton Pass using the pass-cli command-line tool. To get started, you need to log in to Proton Pass first:

pass-cli login

This will start a web login process where you can enter your Proton Pass credentials. Once authenticated, you can add existing SSH keys or create new ones.

Creating a dedicated vault

#

Depending on your needs, you may want to create a dedicated vault for your SSH keys.

A vault is an encrypted digital container that holds your items.³

Vaults can be shared with other users or simply serve as an organizational unit. I don’t recommend sharing your SSH keys vault with others. SSH keys should always be kept private and not shared.

Creating a new vault with pass-cli is easy:

pass-cli vault create --name SSH-Keys

Create or import SSH keys

#

After creating the vault, you can add your SSH keys.

Importing existing SSH keys

#

To import existing SSH keys, you can use the following command:

pass-cli item create ssh-key import \
    --from-private-key "~/.ssh/auth_codeberg" \
    --vault-name "SSH-Keys" \
    --title "auth_codeberg.org" \
    --password

Generating a new SSH key

#

Instead of importing you can directly generate a new SSH key with the following command:

pass-cli item create ssh-key generate \
    --vault-name "SSH-Keys" \
    --title "auth_codeberg.org"

Using the SSH Agent

#

Now that your SSH keys are stored in Proton Pass, you can use the SSH agent to integrate them.

Load SSH keys into your existing SSH agent

#

If you’re already using an ssh-agent, you can load your Proton Pass SSH keys into it:

pass-cli ssh-agent load --vault-name "SSH-Keys"

Use Proton Pass CLI as your SSH agent

#

Alternatively, Proton Pass CLI can also act as a SSH agent itself.

pass-cli ssh-agent start --vault-name "SSH-Keys"

After it starts, you’ll see output similar to the following, with instructions on how to use the new agent:

SSH agent started successfully!
To use this agent, run:
  export SSH_AUTH_SOCK=/Users/youruser/.ssh/proton-pass-agent.sock

Keys will refresh automatically every 3600 seconds (1 hour).

Press Ctrl+C to stop the agent.

Running the SSH agent as a background daemon

#

The Proton Pass SSH agent can also run in the background without keeping a terminal open.

pass-cli ssh-agent daemon start --vault-name "SSH-Keys"

Once it’s running, you can check the status with:

pass-cli ssh-agent daemon status

Similar to pass-cli ssh-agent start, it will output information about the SSH_AUTH_SOCK environment variable, which you must set in your shell configuration to use the agent.

Status:   running
PID:      12345
Socket:   /home/youruser/.ssh/proton-pass-agent.sock

To connect to the agent, set SSH_AUTH_SOCK:
  export SSH_AUTH_SOCK=/home/youruser/.ssh/proton-pass-agent.sock

PID file: /home/youruser/.ssh/proton-pass-agent.pid

The daemon does not modify your shell environment, so you need to set SSH_AUTH_SOCK yourself in ~/.bashrc or ~/.zshrc.

SSH Config

#

Now that your SSH agent is running, you can start using your SSH keys. However, you need to configure the SSH client. Otherwise, you might need to use complicated commands like:

ssh -o "IdentityAgent=${SSH_AUTH_SOCK}" \
    -o "IdentitiesOnly=yes" \
    -i "~/.ssh/auth_codeberg.org.pub" \
    git@codeberg.org

To simplify this, add the following to your ~/.ssh/config file⁴:

# Proton pass-cli SSH agent integration
Host *
    User %u
    IdentityAgent "${SSH_AUTH_SOCK}"
    IdentitiesOnly yes
    IdentityFile ~/.ssh/auth_%h.pub

This will set the following defaults for all SSH connections:

• User %u

  Dynamically sets the remote username to match your current local system username unless explicitly overridden.

• IdentityAgent ${SSH_AUTH_SOCK}

  Forces the SSH client to route all authentication requests through the active Proton Pass CLI agent socket defined in your environment variables.

• IdentitiesOnly yes

  Restricts the client to only offer keys explicitly specified by the IdentityFile directive. This prevents the server from rejecting your connection due to “too many authentication failures” caused by the agent trying unrelated keys.

• IdentityFile ~/.ssh/auth_%h.pub

  Points to a local copy of your public key. The SSH client reads this public key file, extracts its unique fingerprint, and asks the Proton Pass agent to sign the challenge using the matching private key stored in your secure vault. The %h placeholder will be replaced with the hostname of the remote server. For example: if you run ssh git@codeberg.org, the IdentityFile will render to: ~/.ssh/auth_codeberg.org.pub

You might wonder: since we have the SSH key in Proton Pass, how do we get the public keys to ~/.ssh/?

We can export it with:

pass-cli item view --vault-name "SSH-Keys" --item-title auth_codeberg --field "public_key" >"~/.ssh/auth_codeberg.pub"

With all of this in place, you can now simply use:

ssh git@codeberg.org

My Custom Proton Pass SSH Agent Integration

#

By now, you might be thinking: This involves a lot of configuration steps. Manually starting the SSH agent from the CLI every time and ensuring all public keys are exported to ~/.ssh/ is far from convenient.

To reduce friction and make this workflow smoother, I’ve created a script and systemd service to automate everything: https://codeberg.org/tepene/proton-pass-ssh-agent

Once set up, you can:

• Start the Proton Pass CLI authentication process
• Start the Proton Pass SSH Agent
• Export all SSH public keys from your vault to ~/.ssh/

Installation and usage are documented in the README.