keychain-auth start: launch the security daemon

Start the keychain-auth daemon to broker OS keychain access over a local socket with kernel-level process verification and per-connection policy enforcement.

The start command launches the keychain-auth security daemon in the foreground. Once running, the daemon listens on a local Unix domain socket (or Windows Named Pipe) and acts as the sole gatekeeper between your applications and the OS keychain. No client can access keychain secrets unless it is registered and the daemon is running.

Usage

keychain-auth start

To override the socket path:

keychain-auth start --socket /tmp/my.sock

Socket path resolution

The daemon resolves the socket path in the following priority order:

1. The --socket / -s flag value, if provided.
2. The KEYCHAIN_AUTH_SOCKET environment variable, if set.
3. The platform default path.

Platform default paths:

Platform	Default socket path
macOS	~/Library/Application Support/keychain-auth/agent.sock
Linux	$XDG_RUNTIME_DIR/keychain-auth/agent.sock (fallback: ~/.cache/keychain-auth/agent.sock)
Windows	\\.\pipe\keychain-auth

Flags

Flag	Short	Description
--socket <path>	-s	Override the socket path the daemon listens on.

Environment variables

Variable	Description
KEYCHAIN_AUTH_SOCKET	Sets the socket path when --socket is not provided. Useful for service managers and shell profiles.

Live configuration reload

The daemon validates your config.json at startup and exits immediately if the file is malformed. After that, it re-reads the config file on every new connection — you do not need to restart the daemon after changing permissions or registering new binaries. Changes take effect the next time a client connects. On Linux the config lives at ~/.config/keychain-auth/config.json; on macOS at ~/Library/Application Support/keychain-auth/config.json.

Run the daemon as a background service using your OS service manager (launchd, systemd, or Windows Services) so it starts automatically at login.

The daemon runs in the foreground. If you start it in a terminal, closing that terminal stops the daemon and disconnects all active client sessions.