Install keychain-auth on macOS, Linux, and Windows

Download and install the keychain-auth daemon binary, verify the installation, and start the daemon so your tools can connect to it.

keychain-auth ships as a single self-contained binary. Install it on macOS using Homebrew, on Linux using a pre-built binary or your package manager, or on Windows using the released archive. After installation, run keychain-auth start to launch the daemon — your CLI tools can then connect over a local socket.

macOS

Install with Homebrew

The recommended way to install on macOS is via the official Homebrew tap:

brew install The-17/tap/keychain-auth

Homebrew installs the binary to /usr/local/bin/keychain-auth (Intel) or /opt/homebrew/bin/keychain-auth (Apple Silicon) and places the launchd plist at io.keychainauth.daemon.plist inside the Homebrew prefix.

Install manually

Download the latest macOS archive from the GitHub releases page, choosing the correct architecture:

Architecture	Archive name
Apple Silicon (M1/M2/M3)	keychain-auth_<version>_darwin_arm64.tar.gz
Intel	keychain-auth_<version>_darwin_amd64.tar.gz

Extract and install:

tar -xzf keychain-auth_<version>_darwin_arm64.tar.gz
sudo mv keychain-auth /usr/local/bin/keychain-auth
sudo chmod +x /usr/local/bin/keychain-auth

Verify the install

keychain-auth --version

Start the daemon

keychain-auth start

The daemon listens on a Unix domain socket at ~/Library/Application Support/keychain-auth/agent.sock. You can override the path at startup:

keychain-auth start --socket /custom/path/agent.sock

Or set the KEYCHAIN_AUTH_SOCKET environment variable before starting.

Run at login with launchd

If you installed via Homebrew, register the daemon to start automatically at login:

brew services start The-17/tap/keychain-auth

For manual installs, copy the included launchd plist from the release archive to your LaunchAgents directory, then load it:

cp io.keychainauth.daemon.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/io.keychainauth.daemon.plist

Linux

Install with the pre-built binary

Download the latest Linux archive from the GitHub releases page:

Architecture	Archive name
x86_64	keychain-auth_<version>_linux_amd64.tar.gz
ARM64	keychain-auth_<version>_linux_arm64.tar.gz

Extract and install:

tar -xzf keychain-auth_<version>_linux_amd64.tar.gz
sudo mv keychain-auth /usr/local/bin/keychain-auth
sudo chmod +x /usr/local/bin/keychain-auth

Verify the install

keychain-auth --version

Start the daemon

keychain-auth start

The daemon listens on $XDG_RUNTIME_DIR/keychain-auth/agent.sock (or ~/.cache/keychain-auth/agent.sock as fallback). You can override the path:

keychain-auth start --socket /run/user/1000/keychain-auth.sock

Or set the KEYCHAIN_AUTH_SOCKET environment variable.

Run as a systemd service

The release archive includes a systemd unit file. Install it to start the daemon at boot:

sudo cp keychain-auth.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now keychain-auth

Headless and WSL environments

On headless Linux systems and inside WSL (Windows Subsystem for Linux), the GNOME Keyring / KWallet D-Bus backend may not be available. keychain-auth automatically falls back to a secure file-based storage backend in this case:

~/.keychain-auth/keyring.json

No additional configuration is required. The daemon detects the headless environment at startup and switches backends transparently.

The fallback keyring.json file is encrypted at rest. It is created with 0600 permissions, readable only by your user account.

Windows

Install from the release archive

Download the latest Windows archive from the GitHub releases page:

Architecture	Archive name
x86_64	keychain-auth_<version>_windows_amd64.tar.gz

Extract the archive and move keychain-auth.exe to a directory on your PATH, for example C:\Program Files\keychain-auth\.

Verify the install

Open a Command Prompt or PowerShell window and run:

keychain-auth --version

Start the daemon

keychain-auth start

On Windows, the daemon listens on a Named Pipe instead of a Unix socket:

\\.\pipe\keychain-auth

You can override the pipe path at startup:

keychain-auth start --socket \\.\pipe\my-keychain-auth

Run as a Windows service

To start the daemon automatically at login, create a scheduled task or register it as a Windows service using the tool of your choice (for example, NSSM or the built-in sc command).

The daemon integrates with Windows Credential Manager via DPAPI (wincred). Credentials are stored encrypted and tied to your Windows user account.

WSL users

If you are running CLI tools inside WSL and want them to connect to the keychain-auth daemon running on the Windows host, the daemon will use the file-based fallback backend at ~/.keychain-auth/keyring.json within your WSL environment. Start the daemon inside WSL directly for the best experience:

keychain-auth start

Confirm the daemon is accepting connections

After starting the daemon, you can check it is listening by running:

keychain-auth list-pending

A response (even an empty list) confirms the daemon is up and reachable. If you see a connection error, verify the socket path matches between the daemon and your client, or check the daemon logs.

The daemon must be running before any client binary can connect. If you stop the daemon, all in-flight connections are closed and pending requests will fail with a connection error.