SSH Agent Skill

Setup

Prerequisites

1. 1Password CLI (op)

   # macOS
   brew install 1password-cli
   
   # Linux/WSL
   # Download from: https://1password.com/downloads/command-line/

1. Keychain for SSH agent management

   # macOS
   brew install keychain
   
   # Linux (usually pre-installed)
   sudo apt-get install keychain

1. 1Password Service Account (required)

• Create at https://op.serviceaccounts.1password.com
• Add to ~/.zshrc: export OP_SERVICE_ACCOUNT_TOKEN="your-token"

SSH Key Setup

1. Ensure you have an SSH key:

   # Generate if needed
   ssh-keygen -t ed25519 -C "[email protected]"

1. Store the key's passphrase in 1Password:

• Create a new item (e.g., "my-ssh-key")
• Add the passphrase to the Password field
• Save as a Password field type

1. Update ~/.ssh/askpass-1password.sh:

   SSH_KEY_REFERENCE="op://Private/my-ssh-key/password"

Features

Automatic SSH Agent Setup

The setup script (~/.ssh/setup_ssh_agent.sh) automatically:

1. Starts keychain SSH agent
2. Loads your SSH key with 1Password passphrase
3. Sets environment variables for the session

SSH_ASKPASS Integration

When configured, SSH prompts for passphrases are handled by:

1. The 1Password helper script reads from 1Password
2. The passphrase is never stored in plaintext
3. Keychain caches the unlocked key for the session

Keychain Integration

• Keys are unlocked once per session
• Keychain persists the unlocked state
• No password prompts for subsequent SSH operations

Usage

Manual Setup

If not using the automated installer, add to your shell config:

# 1Password CLI (Required first)
export PATH="$HOME/.local/bin:$PATH"

# 1Password Session Manager (Required before SSH)
if [[ -f "$HOME/.config/op-ssh/op-session-manager.sh" ]]; then
  source "$HOME/.config/op-ssh/op-session-manager.sh"
fi

# SSH Keychain with 1Password
_ssh_setup_script="${HOME}/.ssh/setup_ssh_agent.sh"
if [[ -f "$_ssh_setup_script" ]]; then
  source "$_ssh_setup_script"
fi

Check SSH Agent Status

# List loaded keys
ssh-add -l

# Test SSH connection
ssh -T [email protected]

Manually Unlock a Key

# Force unlock with 1Password
export SSH_ASKPASS_REQUIRE="prefer"
export SSH_ASKPASS="${HOME}/.ssh/askpass-1password.sh"
ssh-add ~/.ssh/id_ed25519

Files and Directories

~/.ssh/
├── askpass-1password.sh    # SSH_ASKPASS helper script
├── setup_ssh_agent.sh      # Keychain initialization script
└── id_ed25519*            # Your SSH key(s)

~/.config/op-ssh/
├── .env.1pass              # User-level environment
└── op-ai-helper.sh         # Helper functions

/opt/local/bin/              # Or ~/.local/bin/
└── op-reference            # 1Password CLI wrapper

Platform-Specific Notes

WSL (Windows Subsystem for Linux)

• 1Password desktop app on Windows handles authentication
• SSH Agent enabled in 1Password desktop Settings > Developer
• Socket at: /mnt/c/Users/kyleb/AppData/Local/1Password/sockets/

Native Windows

• Windows OpenSSH agent uses 1Password SSH Agent
• Ensure Windows SSH Agent service is disabled
• 1Password takes over the SSH agent pipe

macOS

• Keychain is pre-installed
• SSH_ASKPASS uses macOS native helpers when available

Troubleshooting

SSH keeps asking for passphrase

Solution: Check SSH_ASKPASS is set correctly:
  echo $SSH_ASKPASS
  echo $SSH_ASKPASS_REQUIRE

"Keychain has no keys in memory"

Solution: Restart keychain:
  keychain --clear
  # Then start a new shell or run:
  source ~/.ssh/setup_ssh_agent.sh

"No reference provided"

Solution: Update ~/.ssh/askpass-1password.sh
  with a valid 1Password secret reference

"Not signed in to 1Password"

Solution: Set OP_SERVICE_ACCOUNT_TOKEN in ~/.zshrc

Keychain Commands

# List active keys
keychain --list

# Clear all keys
keychain --clear

# Show keychain status
keychain --status

# Add specific key
keychain --add ~/.ssh/id_ed25519

# Check key loaded
ssh-add -l

Original Article

Based on: "Combining Keychain and 1Password CLI for ssh-agent management" by Bas Nijholt.