🔑 Credential helpers

AgentKit stores credentials using credential helper binaries — plugin programs found in PATH named agentkit-credential-<name>. Tools that need credentials never manage credential storage directly; they delegate to these helpers via a simple subprocess protocol.

Two helpers ship with AgentKit:

Helper binary	Backend	Use case
agentkit-credential-keychain	System keychain (macOS Keychain, Windows Credential Manager, Linux libsecret via D-Bus)	Desktop workstation with a keychain daemon
agentkit-credential-file	Cleartext JSON file on disk (0600 perms)	Headless server, CI, WSL without D-Bus

Protocol

Helpers accept these commands via argv and return JSON on stdout:

Command	Args	stdin	stdout	Exit code
get	<component> <identity>	—	JSON credential blob	0 = success, 1 = not found
put	<component> <identity>	JSON credential blob	—	0 = success
delete	<component> <identity>	—	—	0 = success
location	<component>	—	Backend path	0 = success

The component argument namespaces credentials per AgentKit component (e.g. switchboard), preventing key collisions between tools. The helper does not enforce any schema on the blob — consumers define their own format. For example, Switchboard expects access_token, refresh_token, expires_at, and account_id fields.

Resolution order

When a tool needs a credential for a provider:

1. If no credential is expected — no credential needed.
2. It looks for agentkit-credential-<helper_name> in PATH (and next to its own binary), then runs <helper> get <identity>.
3. If the helper isn't found or exits non-zero, it falls back to an environment variable named after the identity (e.g. AGENTKIT_SWITCHBOARD_OPENAI_PAYG for Switchboard).
4. If neither produces a value, the provider is unconfigured and excluded from routing.

agentkit-credential-keychain

Uses the system keychain via the keyring-core crate with platform-specific backends:

• macOS: Keychain Services (apple-native-keyring-store).
• Linux: D-Bus Secret Service (dbus-secret-service-keyring-store with Rust crypto).
• Windows: Credential Manager (windows-native-keyring-store).

The service name used in the keychain is agentkit-credential-keychain, keyed by the provider identity.

Usage

agentkit-credential-keychain get switchboard openai_codex_sub
agentkit-credential-keychain put switchboard openai_codex_sub < creds.json
agentkit-credential-keychain delete switchboard openai_codex_sub
agentkit-credential-keychain location switchboard
# → system keychain (service: agentkit-credential-keychain)

agentkit-credential-file

warning

Credentials are stored in cleartext on disk. Consider using credential_helper = "keychain" for better security.

Stores credentials in a JSON file at a platform-specific data directory with 0600 permissions. The directory is created with 0700 permissions on first write.

The path is scoped by component — switchboard resolves to agentkit/switchboard/credentials.json:

Platform	Path
Linux	~/.local/state/agentkit/<component>/credentials.json
macOS	~/Library/Application Support/AgentKit/<component>/credentials.json
Windows	~/AppData/LocalLow/AgentKit/<component>/credentials.json

The file is a JSON object mapping identity strings to credential blobs:

{
  "openai_codex_sub": {
    "access_token": "gho_...",
    "refresh_token": "ghr_...",
    "expires_at": "2026-06-15T00:00:00Z"
  }
}

File locking

The file helper uses a PID-based lock file (credentials.lock next to the credentials file) to prevent concurrent writes. If a lock file from a dead process is found, it is automatically cleaned up. If the locking process is still alive, the operation fails with a message.

Usage

agentkit-credential-file get switchboard openai_codex_sub
agentkit-credential-file put switchboard openai_codex_sub < creds.json
agentkit-credential-file delete switchboard openai_codex_sub
agentkit-credential-file location switchboard
# → /home/user/.local/state/agentkit/switchboard/credentials.json

Configuration

Each tool that uses credential helpers provides its own configuration mechanism, typically a credential_helper field in its config file or a CLI flag. The value is the name resolved as agentkit-credential-<name> in PATH. Default is "keychain".