Troubleshooting Keychain Storage & `keychain-auth`

AgentSecrets delegates all secret storage and decryption operations to the keychain-auth security daemon, which communicates directly with your operating system's native secure credential backends.

Supported Storage Backends

Platform	Storage Backend	Security Layer	Fallback / Interop
macOS	macOS Keychain (`Security.framework`)	AES-256-GCM via Secure Enclave	Process hash attestation via `LOCAL_PEERPID`
Linux (Native)	GNOME Keyring / Secret Service	Kernel-verified `SO_PEERCRED`	Hardware TPM 2.0 Key Sealing (`/dev/tpm0`)
Windows	Windows Credential Manager	DPAPI (User-scoped encryption)	Named Pipe IPC (`\\.\pipe\keychain-auth`)
WSL (Linux VM)	Windows Host Credential Manager	WSL Host Interop Auto-Extraction	Windows `keychain-helper.exe` bridge

Common Issues & Diagnoses

1/ Socket Connection Errors

If the CLI reports that it cannot connect to the keychain-auth socket or pipe:

Check daemon status: Run the daemon diagnostic command to check whether the process is alive:
```
keychain-auth status --json
```
Verify socket location and permissions:
- Linux (System service): Sockets are located at /run/keychain-auth/agent.sock owned by keychain-auth:agentgroup with 0660 permissions. Ensure your user account belongs to the agentgroup group:
```
sudo usermod -aG agentgroup $USER
```
- macOS: Daemon socket defaults to ~/.config/keychain-auth/agent.sock.
- Windows: The daemon listens on named pipe \\.\pipe\keychain-auth.

Restart the daemon:

# Restart daemon via AgentSecrets helper
agentsecrets init
# Or restart directly on macOS/Linux
pkill -x keychain-auth && keychain-auth start &

2WSL (Windows Subsystem for Linux) Setup & Helper Extraction

In WSL environments, running Linux D-Bus services is often unavailable. keychain-auth automatically uses Windows Host Interop:

Automatic extraction: On startup, keychain-auth embeds and extracts keychain-helper.exe into your Windows user directory:
```
C:\Users\<WindowsUser>\.config\keychain-auth\keychain-helper.exe
```
Testing host interop: Verify from inside WSL that the helper can communicate with the Windows Host Credential Manager:
```
/mnt/c/Users/$USER/.config/keychain-auth/keychain-helper.exe version
```
Antivirus / Execution Policy blocks: If Windows Defender or endpoint security blocks the helper execution, add an exclusion for keychain-helper.exe in C:\Users\<WindowsUser>\.config\keychain-auth\.

3Linux Binary Re-Authorization Prompt ()

When you install a new update of agentsecrets or compile from source, its SHA-256 hash changes:

Expected behavior: The next command you execute will prompt for authorization to update /etc/keychain-auth/config.json.

Manual re-authorization:

sudo keychain-auth authorize $(which agentsecrets) AgentSecrets

4Secret Compound Key Namespaces

Secrets in the OS Keychain are stored with compound namespace identifiers to prevent cross-project or cross-environment collision:

workspace_id:project_id:environment:key_name

For example, STRIPE_KEY in the production environment of project proj_payments in workspace ws_acme is stored as:

ws_acme:proj_payments:production:STRIPE_KEY

Switching environments via agentsecrets environment switch staging switches which compound key namespace is read. There is zero risk of a staging secret being resolved during a production deployment.