Skip to main content

OS Keychain & Secret Storage

OpenHuman uses operating system secure credential storage to protect keys that must remain on your device.

On desktop builds, this means:

  • macOS: Keychain
  • Windows: Credential Manager
  • Linux: Secret Service / libsecret

This is the trust root for local key material. OpenHuman does not rely on plaintext .env files or plaintext local config files to store user credentials.

What Goes in the OS Keychain​

OpenHuman uses two types of local key material with the OS keychain:

1. Credential Entries​

When a feature needs a local credential slot, OpenHuman stores it in the platform keychain rather than writing the raw key into a plain config file.

Examples:

  • Provider API keys stored locally
  • Session and bearer tokens that must remain on device
  • Applicable wallet key material

These entries are scoped under OpenHuman's own key namespace and won't conflict with unrelated applications.

2. Master Encryption Key​

Some sensitive values still need to live inside files because the application configuration itself is file-based.

OpenHuman handles this separation by:

  • Storing the key value on disk as encrypted ciphertext
  • Keeping the master key for decryption in the OS keychain

This means your local config and state files can contain encrypted values, with the decryption key not sitting next to them in plaintext.

What Stays Encrypted on Disk​

When OpenHuman needs to persist sensitive app settings locally, it writes ciphertext to disk while keeping the key in the OS keychain.

Local keys covered:

  • BYO API keys for provider support
  • Channel and webhook keys stored in local config
  • Other locally persisted key settings required by desktop features

The encryption format is authenticated, so OpenHuman can detect tampering rather than silently accepting modified ciphertext.

In practice, the security model is:

  • Key is in the keychain
  • Ciphertext is in the file
  • Decrypted only in memory when needed

Why This Is Better Than Plaintext Config​

If your machine has local workspace backups, sync folders, or support packages, keys in plaintext config files are a liability.

Using the OS keychain as the root key store gives OpenHuman a safer separation:

  • Config files can be copied without exposing raw credentials
  • Accidental logs or file checks are unlikely to leak keys
  • Decryption keys are delegated to the platform credential system rather than app-managed plaintext files

Managed Integrations & Local Keys​

Not every key follows the same path.

Managed Integrations​

For default managed integration flows, third-party OAuth tokens are handled by the OpenHuman backend. Your local app doesn't need to keep those provider tokens in plaintext on your machine.

Local BYO Credentials​

When you choose the bring-your-own-key or direct mode path, OpenHuman treats these credentials as local keys, protected by the OS keychain and encrypted disk storage where needed.

Migration from Old Versions​

Old versions may have kept local encryption material in file-based forms.

Current desktop builds migrate that material to the OS keychain while keeping encrypted payloads on disk. The goal is root keys moving out of plain files and into platform credential storage without requiring users to manually re-enter every key.

Next Steps​