Secure token storage is unavailable (no OS keyring service w

Error message

Secure token storage is unavailable (no OS keyring service was found), so Hermes Desktop cannot save remote gateway tokens. Either enable an OS keyring (e.g. GNOME Keyring or KWallet providing org.freedesktop.secrets) and try again, confirm the plain-text storage option when prompted in Settings → Gateway, or set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in your environment.

What it means

Thrown while persisting a remote gateway token when Electron's safeStorage backend reports no OS keyring service (typical on Linux without org.freedesktop.secrets) and the user has not opted into plain-text storage. The function only downgrades to { encoding: 'plain' } when the allowPlainText flag is set; otherwise it refuses to save the secret in the clear.

Source

Thrown at apps/desktop/electron/hardening.ts:192

  const allowPlainText = options?.allowPlainText === true

  let encryptionAvailable = false

  try {
    encryptionAvailable = Boolean(safeStorageApi?.isEncryptionAvailable?.())
  } catch {
    encryptionAvailable = false
  }

  if (!encryptionAvailable) {
    // Only downgrade to plain text when the user has explicitly opted in;
    // decryptDesktopSecret returns the raw value for any non-'safeStorage'
    // encoding, so this round-trips without any decrypt-side change.
    if (allowPlainText) {
      return { encoding: 'plain', value: raw }
    }

    throw new Error(
      'Secure token storage is unavailable (no OS keyring service was found), so Hermes Desktop cannot save remote gateway tokens. ' +
        'Either enable an OS keyring (e.g. GNOME Keyring or KWallet providing org.freedesktop.secrets) and try again, ' +
        'confirm the plain-text storage option when prompted in Settings → Gateway, ' +
        'or set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in your environment.'
    )
  }

  try {
    return {
      encoding: SAFE_STORAGE_ENCODING,
      value: safeStorageApi.encryptString(raw).toString('base64')
    }
  } catch (error) {
    const detail = error instanceof Error && error.message ? ` (${error.message})` : ''
    throw new Error(
      `Failed to encrypt the remote gateway token for secure storage${detail}. ` +
        'Set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in your environment as a fallback.'
    )

View on GitHub (pinned to c896c09c42)

Solutions

Install/enable a keyring providing org.freedesktop.secrets (gnome-keyring or kwallet) and restart the session, then retry.
Confirm the plain-text storage option when prompted in Settings → Gateway (explicit opt-in).
Alternatively set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in the environment so no token needs to be stored.

Defensive patterns

Strategy: fallback

Validate before calling

const { safeStorage } = require('electron')
function canStoreSecretsSecurely() {
  return safeStorage.isEncryptionAvailable()
}

Try / catch

try {
  await saveRemoteToken(token, { allowPlainText: false })
} catch (e) {
  if (/Secure token storage is unavailable/.test(e.message)) {
    promptEnableKeyringOrPlainText()
  } else throw e
}

Prevention

Run a keyring daemon providing org.freedesktop.secrets on Linux
Decide the plain-text policy up front in Settings
Keep HERMES_DESKTOP_REMOTE_URL/TOKEN as an env fallback for headless setups

When it happens

Trigger: Saving a token in Settings → Gateway on Linux running a WM without GNOME Keyring/KWallet (Hyprland, Sway, some minimal setups); headless-ish or containerized desktop sessions where the secrets service D-Bus name is absent; safeStorage.isEncryptionAvailable() returning false for any reason and allowPlainText not passed.

Common situations: Tiling-WM users; distros that don't auto-start a keyring; users who dismissed the plain-text confirmation prompt and retried the save.

Related errors

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/c1cba50e77f2a496. Report an issue: GitHub.