SSH agent

Paw includes a built-in agent that implements the standard OpenSSH agent protocol. It securely holds your unlocked SSH keys in memory and serves authentication requests to tools like ssh, git, and scp.

Your private keys remain encrypted inside your Paw vault and are never written to disk in plaintext.

How it works

1. Automatic loading: Whenever you unlock a vault in the desktop app or via paw cli unlock, Paw automatically loads all SSH keys stored in that vault into the agent keyring.
2. Standard authentication: OpenSSH client tools communicate with Paw over a local socket to perform cryptographic signing.
3. Automatic cleanup: When you lock the vault or close Paw, the keys are immediately removed from the agent’s memory.

Socket configuration

To allow external programs to communicate with Paw, point the SSH_AUTH_SOCK environment variable to Paw’s agent socket.

macOS and Linux

The default agent socket path is:

~/.paw/agent.sock

(If you set a custom PAW_HOME directory, the socket is located at $PAW_HOME/.paw/agent.sock.)

Set the environment variable in your terminal session:

export SSH_AUTH_SOCK="$HOME/.paw/agent.sock"

To make this configuration permanent across terminal sessions, add the export line to your shell configuration file:

• Zsh (default on macOS): Add to ~/.zshrc
• Bash (common on Linux): Add to ~/.bashrc

Windows

On Windows, the agent communicates using a local named pipe:

\\.\pipe\paw

Configure your OpenSSH client or Git for Windows to connect to the named pipe.

Using with the Desktop app

The desktop application manages the agent automatically in the background:

1. Open Paw.
2. Unlock your vault containing your SSH keys.
3. All SSH keys in that vault are instantly available to your terminal tools.
4. When you select Lock vault or quit Paw, the keys are automatically unloaded.

Using with the CLI

If you use Paw without the desktop interface, manage the agent through the command line:

1. Start the agent in a dedicated terminal or service manager:

   paw cli agent start

   Leave this process running in the background.

2. Unlock your vault in another terminal:

   paw cli unlock Personal

   Paw prompts for your vault password. Once unlocked, Paw loads the vault’s SSH keys into the agent and prints a session ID.

3. Check active sessions:

   paw cli agent sessions

4. Lock the vault when finished:

   paw cli lock Personal

Verifying the connection

Once your vault is unlocked and SSH_AUTH_SOCK is set, you can verify that your keys are visible to OpenSSH.

Run ssh-add -l in your terminal:

ssh-add -l

If Paw is unlocked and configured properly, the command prints the fingerprints and comments of your stored keys:

256 SHA256:dK8s7... id_ed25519 (ED25519)
4096 SHA256:mP4k9... production-server (RSA)

If the vault is locked or empty, ssh-add -l outputs:

The agent has no identities.

Using with Git and remote servers

Once configured, any standard SSH operation automatically authenticates using Paw:

# Authenticate with GitHub
ssh -T [email protected]

# Clone, pull, or push repositories
git clone [email protected]:username/repository.git
git push origin main

# Connect to a remote server
ssh [email protected]

The SSH client requests signatures from Paw without asking you for SSH key passphrases.