macOS Keychain

The built-in keychain() resolver lets you load secrets directly from the macOS Keychain using declarative instructions in your .env files. It communicates with the Keychain through Varlock’s native Swift daemon, which enforces biometric authentication (Touch ID) and per-session access control.

Built-in support

No plugin installation is required — keychain() is built into Varlock and available out of the box on macOS.

Or use varlock()

If you don’t already have secrets stored in your macOS Keychain, you may want to use the varlock() resolver instead. It provides the same biometric-gated, device-local encryption benefits without needing to manage Keychain items — and it works cross-platform.

See the local encryption guide for more details.

Features

• Built-in — No plugin or extra dependency needed
• Biometric gating — Access is protected by Touch ID via Varlock’s native daemon
• Interactive picker — Use keychain(prompt) to browse and select items via a native dialog
• Auto-write-back — Prompt mode writes the resolved reference back to your config file
• Named or positional syntax — Flexible argument styles for quick or precise lookups
• Field selection — Extract specific fields from keychain items
• Multiple keychain support — Access the login, System, or custom keychains

Caution

keychain() is only supported on macOS. It will throw an error on other platforms. If your team includes non-Mac developers, consider wrapping keychain items with a fallback or using a cross-platform secrets source for shared configs.

Getting started

Rather than wiring up items individually, the easiest way to get started is by using keychain(prompt). This will open a native picker dialog where you can select existing keychain items, or create new ones. After selection, Varlock will automatically write the resolved reference back into your config file for future use.

ITEM=keychain(prompt) # Opens a native picker dialog

Reference

keychain()

Fetch a secret from the macOS Keychain. Communicates with the Keychain through Varlock’s native daemon, which enforces biometric (Touch ID) authentication.

Array args:

• service (optional): Service name of the keychain item (positional shorthand)
• prompt (optional): Enter interactive picker mode

Key/value args:

• service (optional): Service name of the keychain item
• account (optional): Account identifier for the keychain item
• keychain (optional): Name of a specific keychain to search (e.g., "System")
• field (optional): Specific field to extract from the keychain item
• prompt (optional): If set, opens a native picker dialog for interactive selection

# Positional shorthand
DATABASE_PASSWORD=keychain("com.company.database")

# Named service param
API_KEY=keychain(service="com.company.api")

# With account
ADMIN_PW=keychain("com.company.db", account="admin")

# Targeting a specific keychain
CERT=keychain("com.company.cert", keychain="System")

# Field selection
TOKEN=keychain("com.company.auth", field="password")

# Interactive picker mode
NEW_SECRET=keychain(prompt)

---

Troubleshooting

”keychain() is only supported on macOS”

This resolver requires macOS. It is not available on Linux or Windows. If you need cross-platform secret management, consider using one of the plugin-based secret sources.

Failed to read keychain item

• Verify the item exists in Keychain Access.app
• Check that the service name and account match exactly
• Try keychain(prompt) to browse available items and grant VarlockEnclave access via the native dialog

Selection was cancelled

If you dismiss the native picker without selecting an item, the resolution will fail. Run varlock again to retry, or replace keychain(prompt) with an explicit keychain(service="...") reference.

VarlockEnclave access

The first time you access a keychain item through Varlock, macOS may prompt you to grant access to VarlockEnclave. Approve this to allow future reads. If you accidentally denied access, you can update the item’s Access Control settings in Keychain Access.app.