nativeMessaging

Use this when your extension needs to break out of the browser sandbox to interact with the local operating system or hardware.

Examples:

• A password manager that needs to communicate with its desktop client.
• An extension that controls a hardware device connected to the computer (e.g., a smart card reader).
• A developer tool that needs to interact with a local development server or build tools.

The extension manifest is only half of the setup. The user must separately install a native messaging host on disk: an executable plus a JSON host manifest registered in an OS-specific location.

{
  "name": "My Native App Connector",
  "version": "1.0",
  "manifest_version": 3,
  "permissions": [
    "nativeMessaging"
  ]
}

A minimal native host manifest (e.g., com.my_company.my_application.json) lives outside the extension and looks like this:

{
  "name": "com.my_company.my_application",
  "description": "My native helper",
  "path": "/usr/local/bin/my_native_host",
  "type": "stdio",
  "allowed_origins": [
    "chrome-extension://YOUR_EXTENSION_ID/"
  ]
}

Chrome looks for this file in OS-specific locations:

• Windows: registered under HKLM\Software\Google\Chrome\NativeMessagingHosts\com.my_company.my_application (or HKCU\...) pointing at the JSON path.
• macOS: /Library/Google/Chrome/NativeMessagingHosts/com.my_company.my_application.json (system) or ~/Library/Application Support/Google/Chrome/NativeMessagingHosts/... (user).
• Linux: /etc/opt/chrome/native-messaging-hosts/com.my_company.my_application.json (system) or ~/.config/google-chrome/NativeMessagingHosts/... (user).

Why is it very high risk?

This permission opens a pipe between the extension and a native helper executable that runs entirely outside the browser sandbox. Whatever the user's OS account can do, the helper can do — read/write any file the user can, execute commands, talk to the network, persist as a startup item, etc.

• The permission itself just opens the channel; the capability lives in the native binary on the other end.
• Any compromise of the extension or the helper effectively becomes full user-level code execution on the device.
• Chrome cannot enforce per-message review of what flows over the channel; the helper sees everything the extension sends.

Only grant nativeMessaging to extensions where you trust both the extension and the separately-installed native binary at the level you'd trust any other desktop application. This is the single most powerful permission an extension can request.

This example connects to a native messaging host and sends it a message.

// background.js

// The name must match the one specified in the native host's manifest file.
const hostName = "com.my_company.my_application";
const port = chrome.runtime.connectNative(hostName);

console.log("Connecting to native host...");

port.onMessage.addListener((message) => {
  console.log("Received message from native host:", message);
});

port.onDisconnect.addListener(() => {
  if (chrome.runtime.lastError) {
    console.error("Disconnected with an error:", chrome.runtime.lastError.message);
  } else {
    console.log("Disconnected from native host.");
  }
});

// Send a message
const message = { text: "Hello from the extension!" };
port.postMessage(message);