Homeboy manages SSH keys for remote server access, including keychain integration for passphrase management.

Overview

SSH keys in Homeboy are stored as file references in server configurations (identity_file field) with passphrases stored securely in the OS keychain.

Key Locations

SSH keys are stored on the local filesystem, not in Homeboy configuration:

Standard locations:

• macOS/Linux: ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
• Windows: %USERPROFILE%.sshid_rsa, %USERPROFILE%.sshid_ed25519

Homeboy references these keys via absolute paths in server configuration.

Server Configuration

SSH key configuration is part of server definition in servers/<server_id>.json:

{
  "id": "production",
  "name": "Production Server",
  "host": "example.com",
  "port": 22,
  "user": "deploy",
  "identity_file": "/Users/dev/.ssh/id_ed25519",
  "forward_agent": true
}

Fields

• identity_file (string): Absolute path to SSH private key
• forward_agent (boolean): Enable SSH agent forwarding

Key Generation

Generate a new SSH key pair:

ssh-keygen -t ed25519 -C "[email protected]"

# Generate RSA key (legacy compatibility)
ssh-keygen -t rsa -b 4096 -C "[email protected]"

During generation:

1. Accept default location or specify custom path
2. Enter a strong passphrase (recommended)
3. Confirm passphrase

The passphrase is stored in keychain on first use.

Key Deployment

Copy Public Key to Server

# Using ssh-copy-id (recommended)
ssh-copy-id user@hostname

# Manual copy
cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"

Add to Server Configuration

homeboy server create production 
  --host example.com 
  --user deploy 
  --identity-file ~/.ssh/id_ed25519

Passphrase Management

Initial Storage

When you first use an SSH key with Homeboy, the passphrase is cached in the OS keychain:

homeboy ssh <project_id>

If the key has a passphrase, Homeboy:

1. Prompts for passphrase
2. Stores passphrase in keychain
3. Uses keychain for subsequent connections

Passphrase Retrieval

Passphrases are automatically retrieved from keychain when:

• Establishing SSH connections via homeboy ssh
• Running remote commands via SSH
• Uploading files to remote servers

No manual passphrase entry is required after initial storage.

Passphrase Updates

To change an SSH key’s passphrase:

ssh-keygen -p -f ~/.ssh/id_ed25519

This updates the key file. Homeboy will detect the new passphrase on next use and update the keychain entry.

Delete Cached Passphrase

Remove cached passphrase from keychain:

macOS:

security delete-generic-password -s homeboy -a ssh_key_<identity_file_hash>

Linux:

secret-tool clear homeboy ssh_key_<identity_file_hash>

Windows:

cmdkey /delete:ssh_key_<identity_file_hash>

Note: The exact key name depends on the key file path hash.

SSH Agent Forwarding

When forward_agent is enabled in server configuration, SSH keys from your local agent are forwarded to the remote server.

Benefits

• Remote servers can use your local SSH keys
• Enables Git operations on remote server using your credentials
• Reduces need for keys on remote servers

Configuration

homeboy server set production --forward-agent true

Security Considerations

SSH agent forwarding grants the remote server access to your forwarded SSH identities. Enable only on trusted servers.

Key Types

ED25519 (Recommended)

Modern, secure, and fast:

ssh-keygen -t ed25519 -C "[email protected]"

RSA (Legacy)

For compatibility with older systems:

ssh-keygen -t rsa -b 4096 -C "[email protected]"

ECDSA

Alternative to RSA:

ssh-keygen -t ecdsa -b 521 -C "[email protected]"

Troubleshooting

Key Permission Errors

SSH keys must have restrictive permissions:

chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub

Passphrase Prompt Loop

If Homeboy repeatedly prompts for passphrase:

1. Verify key file path in server configuration is correct
2. Delete cached passphrase from keychain
3. Test key passphrase: ssh -i ~/.ssh/id_ed25519 user@hostname

Connection Refused

Check:

• Server is accessible: ping hostname
• SSH port is correct (default: 22)
• Firewall allows SSH connections
• User has SSH access on remote server

Agent Forwarding Not Working

If agent forwarding fails:

1. Verify SSH agent is running: ps aux | grep ssh-agent
2. Add keys to agent: ssh-add
3. Verify server configuration has forward_agent: true

Best Practices

1. Use ED25519 keys: More secure and faster than RSA
2. Always use passphrases: Protect keys with strong passphrases
3. Separate keys per server: Use different keys for different environments
4. Rotate keys regularly: Generate new keys periodically
5. Disable password authentication: Configure servers to only allow key-based authentication
6. Limit agent forwarding: Enable only on trusted servers
7. Back up keys: Store private key backups in secure, offline storage

Related

• Server command – Manage server configuration
• SSH command – Remote shell access
• Server schema – Server configuration structure
• Keychain/secrets management – Passphrase storage