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

9installs
Sourcesoulmachine/skills
Added on

NPX Install

npx skill4agent add soulmachine/skills ssh-keychain-unlock

Tags

Translated version includes tags in frontmatter
claude-codessh-keychainmacos-automationremote-accessheadless-setup

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 
600
):
bash
echo 'YOUR_MACOS_PASSWORD' > ~/.claude/.keychain-password
chmod 600 ~/.claude/.keychain-password
2. Create unlock script (
~/.claude/unlock-keychain.sh
, permissions 
700
):
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

CommandPurpose
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.