SSH with 1Password

What is SSH?

SSH (Secure Shell) is a cryptographic network protocol for secure communication between machines over an unsecured network. It is the standard way to remotely access servers, push code to Git repositories, and transfer files.

SSH uses public-key cryptography. You generate a key pair — a private key (kept secret) and a public key (shared with servers). When you connect, the server verifies your identity using the public key without ever seeing your private key.

Ed25519 vs RSA

Use Ed25519 for all new keys. It is faster, more secure, and produces shorter keys. RSA is only needed for compatibility with very old systems.

Prerequisites

None — this is a foundational guide.

Generate an SSH Key in 1Password

Instead of managing SSH keys as files on disk, 1Password can generate, store, and serve your keys through its built-in SSH agent. This means your private key never touches the filesystem.

1. Open 1Password and create a new SSH Key item
2. Select Ed25519 as the key type
3. Give it a descriptive title (e.g., Personal SSH Key)
4. Save the item — 1Password stores both the private and public key

Copy the public key from the item details — you will need it for adding to remote machines and Git hosts.

Configure the 1Password SSH Agent

~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock

Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

~/.1password/agent.sock

Host *
  IdentityAgent ~/.1password/agent.sock

Configure Which Keys the Agent Exposes

By default, the 1Password SSH agent exposes all SSH keys across all your vaults. If you have multiple vaults or want to restrict which keys are available, create an agent config file:

mkdir -p ~/.config/1password/ssh

Edit ~/.config/1password/ssh/agent.toml:

[[ssh-keys]]
vault = "Private"

[[ssh-keys]]
vault = "Work"

Each [[ssh-keys]] entry specifies a vault to draw keys from. You can also pin a specific key by its item name:

[[ssh-keys]]
item = "Personal SSH Key"
vault = "Private"

Without this file, the agent serves all SSH keys from all vaults. If you only have one vault, you do not need to create this file.

Add Your Public Key to Remote Machines

When using 1Password as your SSH agent, the public key file may not exist on disk. You can either save it from 1Password or paste it directly.

Option 1: Save the public key from 1Password, then use ssh-copy-id:

# Copy your public key from 1Password and save it to disk
echo "ssh-ed25519 AAAA...your-public-key" > ~/.ssh/id_ed25519.pub

# Copy it to the remote server
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@remote-host

Option 2: Paste the public key directly on the remote server:

# On the remote server, append your public key
echo "ssh-ed25519 AAAA...your-public-key" >> ~/.ssh/authorized_keys

For GitHub or GitLab, add the public key in your account settings under SSH Keys.

Verify the Agent Works

List the keys available through the agent:

ssh-add -l

You should see your Ed25519 key fingerprint. Test a connection:

# GitHub
ssh -T git@github.com

# Remote server
ssh user@remote-host

1Password will prompt you to authorize the connection via biometrics or your master password.

Multi-Host SSH Config

In practice, you often access the same server through different networks. Define separate host entries for each access path, with Host * at the bottom to provide shared settings like the 1Password agent:

# Local network
Host homelab-local
  HostName <your-server-lan-ip>
  User your-username
  Port 2222

# Tailscale
Host homelab-ts
  HostName 100.x.x.x
  User your-username
  Port 2222

# Cloudflare Tunnel (no Port needed — tunnel handles it)
Host homelab-cf
  HostName ssh.yourdomain.com
  User your-username
  ProxyCommand cloudflared access ssh --hostname %h

# Shared settings (must be last — Host * is a wildcard)
# macOS:
Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"
# Linux:
# Host *
#   IdentityAgent ~/.1password/agent.sock

Platform-specific: The IdentityAgent path differs between macOS and Linux. Use the macOS path shown above, or the Linux path (~/.1password/agent.sock). See the Configure the 1Password SSH Agent section for both paths.

Tailscale provides a WireGuard-based VPN overlay that assigns each device a stable 100.x.x.x address. This lets you SSH to your server from anywhere without exposing ports to the public internet. On the server, enable the Tailscale service:

sudo systemctl enable --now tailscaled
tailscale up

Once connected, use the Tailscale IP in your SSH config as shown in the homelab-ts entry above.

Put Host * last. SSH reads the config top-to-bottom and multiple Host stanzas can match. For each setting, the first matching value wins. Placing Host * at the end ensures specific entries take precedence over the wildcard defaults.

Non-standard ports: When the server runs SSH on a port other than 22, add Port 2222 to the host entry. When using a Cloudflare Tunnel, the port is defined in the tunnel’s config.yml — the client entry does not need it.

Sign Git Commits with Your SSH Key

Since 1Password already manages your SSH key, you can use the same key to sign Git commits and tags. This proves that commits came from you — GitHub and GitLab display a Verified badge next to signed commits.

1. Configure Git to Sign with SSH

git config --global gpg.format ssh
git config --global gpg.ssh.program "/Applications/1Password.app/Contents/MacOS/op-ssh-sign"
git config --global commit.gpgsign true
git config --global tag.gpgSign true

git config --global gpg.format ssh
git config --global gpg.ssh.program "/opt/1Password/op-ssh-sign"
git config --global commit.gpgsign true
git config --global tag.gpgSign true

2. Set Your Signing Key

Copy your public key from 1Password (the same one you use for SSH) and set it as your signing key:

git config --global user.signingkey "ssh-ed25519 AAAA...your-public-key"

3. Create an Allowed Signers File

Git needs an allowed signers file to verify signatures locally. This maps email addresses to trusted public keys:

# Create the file with your email and public key
echo "your-email@example.com ssh-ed25519 AAAA...your-public-key" > ~/.ssh/allowed_signers

# Tell Git where to find it
git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers

4. Upload Your Signing Key to GitHub

1. Go to GitHub → Settings → SSH and GPG keys
2. Click New SSH key
3. Set Key type to Signing Key
4. Paste your public key and save

You can use the same public key for both authentication and signing. Add it twice — once as an Authentication Key and once as a Signing Key.

5. Verify It Works

Make a commit and check the signature:

git commit --allow-empty -m "test: verify commit signing"
git log --show-signature -1

You should see Good "git" signature for your-email@example.com in the output. On GitHub, the commit will display a Verified badge.

Troubleshooting

Permission denied (publickey)

• Verify the agent is running: ssh-add -l should list your key
• Check that ~/.ssh/config has the correct IdentityAgent path
• Ensure your public key is in the server’s ~/.ssh/authorized_keys

Agent returns no identities

• Confirm 1Password is unlocked
• Re-enable Use the SSH agent in 1Password settings
• On Linux, verify you are not using the Snap or Flatpak version

signing failed for ED25519 on Linux

If SSH operations (like git pull) hang or fail with a signing error, 1Password is waiting for you to approve the key usage in the GUI. Open the 1Password window and approve the prompt. To avoid this in the future, select Approve and Remember when prompted.

Bad owner or permissions on ~/.ssh/config

SSH requires strict permissions on config files:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/config

Resources

🔗

1Password SSH Documentation developer.1password.com

Official guide for using 1Password as your SSH agent

🔗

OpenSSH openssh.org

The OpenSSH project homepage with documentation and release notes