How do I unlock the keychain for headless sessions?

[still pumice]

Unlock keychain for headless sessions? How?

[bitter heath]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[noble vector]

This is a common macOS headless session issue! When running via SSH or in a headless environment, the keychain stays locked by default. Here are the main approaches:

1. Unlock on login (add to your startup):

security unlock-keychain -p "your_password" ~/Library/Keychains/login.keychain-db

2. For automatic/scripted sessions (less secure):

• Set export SECURITY_SESSION_INFO=0 before commands
• Or use ssh -A to forward agent, then unlock once locally first

3. For Clawdbot specifically:
If you're running Clawdbot via SSH or in a container/headless VM on macOS:

• Make sure the user session is fully logged in (GUI session active)
• You can unlock the keychain in a startup script
• Some users add it to their .bashrc or .zshrc:

# Add to ~/.zshrc or ~/.bashrc
security unlock-keychain -p "$KEYCHAIN_PASSWORD" 2>/dev/null || true

4. Alternative: Use keychain items instead of password

# Add your credentials to keychain, reference them in scripts
security add-internet-password -a "youruser" -s "api.example.com" -w "password123"

⚠️ Security note: Putting passwords in env vars or scripts has risks. For production, consider:

• SSH certificates instead of passwords
• macOS Touch ID with secure enclave
• Clawdbot's built-in credential management

What's your use case? SSH into a Mac mini for Clawdbot? That setup has some quirks I can help with!

[still pumice]

The keychain is unlocked and gh can see the entry (gh:github.com), but the token is being read as invalid. This is likely an ACL issue — macOS keychains have permissions that restrict headless processes even after unlocking. SEems like a problem. No cleaner way to do this?

[noble vector]

Yeah, that's the ACL edge case on macOS — even unlocked, headless processes get blocked. Cleanest solutions:

1. Bypass keychain entirely (recommended for headless):

# Get token and export it
export GH_TOKEN=$(gh auth token)

Or set it permanently:

export GITHUB_TOKEN=$(gh auth token)

Add to your shell profile (~/.zshrc) before starting Clawdbot.

2. Recreate the item with relaxed ACLs:

# Delete and re-add with allow-all access

gh auth logout
gh auth login -s "repo,read:org" -w
# When prompted, choose to store token in keychain with "Always Allow"

3. Fix existing keychain ACL via Terminal:

# Show current ACLs
security dump-keychain ~/Library/Keychains/login.keychain-db | grep -A5 "github.com"

# Reset access for the gh item
security set-keychain-settings -l -u ~/Library/Keychains/login.keychain-db

4. For persistent headless setups, use a dedicated keychain:

security create-keychain -p "temp" ~/headless.keychain
security set-keychain-settings -l -u ~/headless.keychain
security unlock-keychain -p "temp" ~/headless.keychain
# Add your gh token here

For Clawdbot specifically — the cleanest way is just exporting GITHUB_TOKEN before starting. That's what most headless CI/CD setups do. It's explicit, debuggable, and avoids the macOS ACL entirely.

[still pumice]

But what if I repeatedly want to be able to use the keychain for LOTS of things? In fact, ... I'd prefer clawdbot to have ALL the access...

[noble vector]

For "everything access," the nuclear option is to make your login keychain never auto-lock:

# Disable auto-lock entirely (both sleep and timeout)
security set-keychain-settings -l -u ~/Library/Keychains/login.keychain-db

Then unlock once at session start:

security unlock-keychain -p "your_password" ~/Library/Keychains/login.keychain-db

After this:

• Keychain stays unlocked indefinitely
• No ACL restrictions for any app
• Full access for SSH/shell processes

Tradeoffs:

• ✅ Clawdbot (and anything) can read/write everything
• ⚠️ If someone gains shell access, they have full keychain too
• ⚠️ Physical access = full keychain access

For a middle ground — a "Clawdbot keychain":

# Create a dedicated keychain for Clawdbot
security create-keychain -p "strong_password" ~/Library/Keychains/clawdbot.keychain

# Never auto-lock
security set-keychain-settings -l -u ~/Library/Keychains/clawdbot.keychain

# Unlock on startup
security unlock-keychain -p "strong_password" ~/Library/Keychains/clawdbot.keychain