ssh-keychain-unlock

Original：🇺🇸 English

Translated

Use when Claude Code auth fails over SSH on macOS, keychain is locked in headless/remote sessions, or setting up Claude Code on a Mac for remote access

7installs

Sourcesoulmachine/skills

Added on2026-05-20

NPX Install

npx skill4agent add soulmachine/skills ssh-keychain-unlock

SKILL.md Content

View Translation Comparison →

SSH Keychain Unlock for Claude Code on macOS

Overview

Claude Code stores credentials in the macOS Keychain (

Claude Code-credentials

service). When accessing a Mac via SSH (no GUI session), the login keychain is locked, causing Claude Code to appear unauthenticated.

When to Use

Claude Code says it's not logged in when accessed via SSH

security show-keychain-info ~/Library/Keychains/login.keychain-db

shows the keychain is locked

Setting up a Mac Mini or headless Mac for remote Claude Code usage

Solutions

Option 1: Interactive Unlock on SSH Login

Add to

~/.zshrc

:

bash

# Unlock macOS keychain for SSH sessions (needed for Claude Code auth)
if [[ -n "$SSH_CONNECTION" ]]; then
  security unlock-keychain ~/Library/Keychains/login.keychain-db 2>/dev/null
fi

Prompts for macOS login password each SSH session. Simple but requires manual input.

Option 2: Auto-Unlock at Boot (Headless)

For fully headless operation with no password prompt:

1. Create password file (

~/.claude/.keychain-password

, permissions

):

bash

echo 'YOUR_MACOS_PASSWORD' > ~/.claude/.keychain-password
chmod 600 ~/.claude/.keychain-password

2. Create unlock script (

~/.claude/unlock-keychain.sh

, permissions

):

bash

cat > ~/.claude/unlock-keychain.sh << 'SCRIPT'
#!/bin/bash
security unlock-keychain -p "$(cat ~/.claude/.keychain-password)" ~/Library/Keychains/login.keychain-db
SCRIPT
chmod 700 ~/.claude/unlock-keychain.sh

3. Create LaunchAgent (

~/Library/LaunchAgents/com.claude.unlock-keychain.plist

):

bash

cat > ~/Library/LaunchAgents/com.claude.unlock-keychain.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude.unlock-keychain</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>__HOME__/.claude/unlock-keychain.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
PLIST
# Fix path
sed -i '' "s|__HOME__|$HOME|g" ~/Library/LaunchAgents/com.claude.unlock-keychain.plist

4. Load the agent:

bash

launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist

Quick Reference

Command	Purpose
`security show-keychain-info ~/Library/Keychains/login.keychain-db`	Check keychain lock status
`security unlock-keychain ~/Library/Keychains/login.keychain-db`	Manually unlock (interactive)
`bash ~/.claude/unlock-keychain.sh`	Test auto-unlock script
`launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	Load LaunchAgent
`launchctl unload ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	Unload LaunchAgent

Common Mistakes

Wrong permissions on password file - Must be
```
600
```
(owner-only). Others can read your macOS password otherwise.
Forgetting to load the LaunchAgent - Creating the plist isn't enough; run
```
launchctl load
```
to activate it.
Password file out of sync - If you change your macOS password, update
```
~/.claude/.keychain-password
```
too.

ssh-keychain-unlock

NPX Install

Tags

SKILL.md Content

SSH Keychain Unlock for Claude Code on macOS

Overview

When to Use

Solutions

Option 1: Interactive Unlock on SSH Login

Option 2: Auto-Unlock at Boot (Headless)

Quick Reference

Common Mistakes