Native Messaging Manifest Lookup

This article explains how Misubi Browser looks for Native Messaging manifests and why integrations such as KeePassXC Browser can appear inconsistent across different machines.

Overview

Misubi Browser uses Misubi-specific primary paths for Native Messaging manifests on macOS and Linux, but it still keeps fallback lookup paths for Chromium, Google Chrome, and Brave.

The practical result is:

• new Misubi installations should place the manifest in the Misubi path
• older manifests stored for Chromium, Chrome, or Brave can still be discovered as fallbacks
• if allow_user_level_hosts=false, user-level paths or registry keys are skipped and only system-level sources are checked

There is one major platform difference:

• macOS and Linux search for a file named <host>.json in a list of directories
• Windows does not search directories directly and instead reads the manifest path from the registry

macOS

On macOS, Misubi checks user-level directories first and then system-level directories.

User-level lookup order

1. ~/Library/Application Support/Misubi/NativeMessagingHosts
2. ~/Library/Application Support/Chromium/NativeMessagingHosts
3. ~/Library/Application Support/Google/Chrome/NativeMessagingHosts
4. ~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts

System-level lookup order

1. /Library/Application Support/Misubi/NativeMessagingHosts
2. /Library/Application Support/Chromium/NativeMessagingHosts
3. /Library/Google/Chrome/NativeMessagingHosts
4. /Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts

Important notes for macOS

• The primary Misubi path is Misubi/NativeMessagingHosts.
• If the manifest is not found there, the browser continues with the Chromium path, then Google Chrome, then Brave.
• This means a host can still work even after the Misubi folder was removed, as long as the same manifest still exists in one of the fallback locations.

Linux

On Linux, Misubi also checks user-level directories first and then system-level directories.

Config base directory

The <config> base directory is resolved in this order:

1. $CHROME_CONFIG_HOME, if set
2. $XDG_CONFIG_HOME, if set
3. ~/.config

User-level lookup order

1. <config>/misubi/NativeMessagingHosts
2. <config>/chromium/NativeMessagingHosts
3. <config>/google-chrome/NativeMessagingHosts
4. <config>/BraveSoftware/Brave-Browser/NativeMessagingHosts

System-level lookup order

1. /etc/misubi/native-messaging-hosts
2. /etc/chromium/native-messaging-hosts
3. /etc/opt/chrome/native-messaging-hosts
4. /etc/brave/native-messaging-hosts

Important notes for Linux

• The primary user path for Misubi is built explicitly as misubi/NativeMessagingHosts.
• It does not depend on Chromium's general user-data-dir.
• Existing manifests stored for Chromium, Chrome, or Brave are still valid fallback targets.

Windows

On Windows, Native Messaging host discovery is registry-based rather than directory-based.

Root key order

1. HKCU, if user-level hosts are allowed
2. HKLM

If allow_user_level_hosts=false, the HKCU branch is skipped.

Registry path order inside each root key

1. SOFTWARE\Misubi\NativeMessagingHosts\<host>
2. SOFTWARE\Chromium\NativeMessagingHosts\<host>
3. SOFTWARE\Google\Chrome\NativeMessagingHosts\<host>
4. SOFTWARE\BraveSoftware\Brave-Browser\NativeMessagingHosts\<host>

Registry view order inside each path

1. 32-bit view
2. 64-bit view

Important notes for Windows

• The registry value stores the absolute path to the manifest file.
• The browser does not walk a folder tree on Windows.
• A host can still resolve from Chromium, Chrome, or Brave registry keys if the Misubi key is missing.

Why things can still work after removing the Misubi folder

This is the most common source of confusion during integration checks.

On macOS and Linux, Misubi does not stop after checking the Misubi-specific directory. If the manifest is missing there, it continues through the fallback order.

For example, on macOS, removing:

• ~/Library/Application Support/Misubi/NativeMessagingHosts

does not necessarily break the host. Misubi will continue checking:

• ~/Library/Application Support/Chromium/NativeMessagingHosts
• ~/Library/Application Support/Google/Chrome/NativeMessagingHosts
• ~/Library/Application Support/BraveSoftware/Brave-Browser/NativeMessagingHosts

If the same host manifest still exists in the Chromium path, the integration can continue to work and look as if Misubi did not need its own folder at all.

The same fallback logic applies on Linux, and the registry fallback order applies on Windows.

Canonical location today

The canonical location for new Misubi installations is the Misubi-specific path or registry branch:

• macOS: ~/Library/Application Support/Misubi/NativeMessagingHosts or /Library/Application Support/Misubi/NativeMessagingHosts
• Linux: <config>/misubi/NativeMessagingHosts or /etc/misubi/native-messaging-hosts
• Windows: SOFTWARE\Misubi\NativeMessagingHosts\<host> under HKCU or HKLM

Fallback support exists for compatibility, but it should be treated as compatibility behavior, not as the preferred installation target.

KeePassXC integration note

This matters directly for KeePassXC Browser, because many users already have a working Native Messaging manifest created for Chromium, Google Chrome, or Brave before they try Misubi Browser.

That creates a few common scenarios:

• KeePassXC integration works in Misubi even though no Misubi-specific manifest was installed yet, because Misubi found an older fallback manifest.
• A user deletes the Misubi-specific directory and the integration still works, which makes it look like the Misubi path is ignored, while in reality the browser is using a fallback location.
• A user has multiple manifests across different browser directories and is not sure which one is currently being used.

If KeePassXC Browser is unreliable, the safest approach is:

1. Install or regenerate the Native Messaging manifest for the Misubi-specific location first.
2. Verify whether older Chromium, Chrome, or Brave manifests are also present.
3. Remove ambiguity during debugging by confirming which manifest path actually exists and which binary path it points to.

KeePassXC example on macOS

On macOS, a common KeePassXC manifest location for Misubi Browser is:

~/Library/Application Support/Misubi/NativeMessagingHosts/org.keepassxc.keepassxc_browser.json

Place a manifest file there with content like this:

{
"allowed_origins": [
  "chrome-extension://pdffhmdngciaglkoonimfcmckehcpafo/",
  "chrome-extension://oboonakemofpalcgghocfoadofidjkkk/"
],
"description": "KeePassXC integration with native messaging support",
"name": "org.keepassxc.keepassxc_browser",
"path": "/Applications/KeePassXC.app/Contents/MacOS/keepassxc-proxy",
"type": "stdio"
}

Make sure the file name matches the host name exactly and make sure the path value points to a valid KeePassXC proxy binary on the machine.

What else matters during troubleshooting

• On macOS and Linux, the browser looks for the exact file name <host_name>.json.
• On Windows, the registry value must point to a valid absolute manifest path.
• Even if the manifest is found, the host still will not start if the path field inside the manifest is broken or if the target binary does not exist.
• On POSIX platforms, the browser creates the primary user directory for DIR_USER_NATIVE_MESSAGING at startup, but it does not automatically create fallback directories.

Practical recommendation

For support cases and install instructions, treat the Misubi-specific path as the official target and treat Chromium, Chrome, and Brave locations only as fallbacks.

If a user reports that KeePassXC works "only sometimes" or "even after deleting the Misubi folder", check fallback manifests first before assuming the Misubi-specific installation failed.