Skip to content

Instantly share code, notes, and snippets.

@jackkav

jackkav/breaking changes.md Secret

Created June 15, 2026 06:50
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jackkav/c228777e9a469fee404d37fa93b2d73d to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jackkav/c228777e9a469fee404d37fa93b2d73d to your computer and use it in GitHub Desktop.
Download ZIP
breaking changes
Raw
breaking changes.md

Insomnia Plugins: Breaking Changes Notice

Audience: Insomnia users who install plugins, and plugin authors. What changed: Insomnia now runs the main application window with nodeIntegration disabled, and runs all plugins in a separate, hidden background window. This is a security hardening change with a small set of breaking changes for some plugins.

TL;DR

  • The main Insomnia UI no longer has direct access to Node.js (require, fs, path, process, Buffer, etc.). This closes a long-standing security exposure where any code running in the UI had full Node.js and filesystem access.
  • Plugins keep their full Node.js access. They now run in a dedicated hidden background window instead of inside the UI. For most plugins, nothing changes and no action is required.
  • A small number of plugins will break — specifically those that reached directly into the UI/renderer (DOM, window globals, React state, shared in-memory objects) or that returned values that cannot be serialized across a process boundary.
  • This hidden-window arrangement is temporary. It is an interim step while we design a proper, permissioned plugin sandbox. Plugin trust and capabilities are unchanged for now.

Why this change

Until now, the Insomnia UI ran with nodeIntegration: true. That meant any code executing in the renderer — the app itself, third-party plugins, and in the worst case injected/malicious content — had unrestricted access to Node.js APIs and your filesystem.

Disabling nodeIntegration in the main window removes that blast radius. The UI can no longer call Node.js directly; it talks to the privileged main process over well-defined, audited channels instead.

Plugins, however, legitimately need Node.js (filesystem access, network libraries, require-ing modules, etc.). To preserve that without re-opening the security hole in the UI, plugins were moved out of the UI window and into a separate hidden window that still has Node.js enabled. The UI now communicates with that window asynchronously over an internal bridge.

This is a deliberate, temporary trade-off. The hidden window still grants plugins full trust (nodeIntegration: true). It is the stepping stone toward a future sandbox (see Roadmap), not the end state.

What this means for you

If you only use plugins

In almost all cases: nothing to do. Installed plugins continue to load and run with the same capabilities as before. You may notice plugin actions, template tags, and request/response hooks behave identically.

If a plugin misbehaves after updating Insomnia (e.g. an action does nothing, or a template tag errors), it is likely affected by one of the breaking changes below — please report it to the plugin's author and link them to this notice.

If you author plugins

Review the breaking changes below. Most well-behaved plugins that use the documented plugin context (context.app, context.store, context.request, context.response, context.network, context.data) need no changes — those APIs were already asynchronous and already crossed a boundary.

Breaking changes

Your plugin is affected only if it does one of the following.

1. Reaching directly into the UI / renderer

Because plugins no longer run in the same window as the UI, anything that depended on shared, in-process access to the renderer no longer works:

  • Accessing window.document, document.querySelector, or manipulating the DOM of the Insomnia UI.
  • Reading or mutating React state, component instances, or other UI internals.
  • Reading global variables set by the UI, or sharing a live object/singleton with UI code.

What to do: Use the supported plugin context APIs (context.app.alert, context.app.dialog, context.app.prompt, etc.) for any UI interaction. Direct DOM/UI access has never been a supported plugin API and is not supported going forward.

2. Returning or passing non-serializable values

All communication between the UI and the plugin window crosses a process boundary and is JSON-serialized. Values that cannot survive JSON serialization will not cross intact:

  • Functions and callbacks returned to the host.
  • Class instances (only their plain data survives; methods/prototypes are lost).
  • Symbols, Map/Set (converted, not preserved as-is), circular references.
  • Raw streams or live handles passed back to the UI.

What to do: Return plain, JSON-serializable data (objects, arrays, strings, numbers, booleans, null). Convert/serialize anything else before returning it.

3. Assuming synchronous coupling with the UI

Plugin invocations are now fully asynchronous across the bridge. Code that assumed it could synchronously block or immediately observe a UI-side effect may need to await instead.

What to do: Treat all host interactions as async/await. (Most plugin context methods already returned Promises.)

4. Long-running operations may time out

The plugin bridge enforces timeouts:

  • ~10 seconds for the plugin window to become ready at startup.
  • ~30 seconds per individual plugin invocation (a hook, action, or template-tag call).

A plugin operation that exceeds 30 seconds (e.g. a slow network call or heavy file processing inside a request/response hook) will be aborted with a timeout error.

What to do: Keep individual hook/action/template-tag executions well under 30 seconds. Move long work off the critical path, or break it into smaller steps.

What is not changing

To be clear about scope:

  • The documented plugin API surface is unchanged. context.app, context.store, context.request, context.response, context.network, and context.data all behave as before.
  • Plugins still have full Node.js access in their window — require(), fs, path, etc. continue to work.
  • Plugin trust level is unchanged. Plugins are not yet sandboxed or permission-gated. Continue to install only plugins you trust.
  • All plugin hook types are still supported: request hooks, response hooks, template tags, request/request-group/workspace/document actions, and themes.

Roadmap

This change is the first step of a phased migration:

  1. Now — interim hidden window. Plugins run in a dedicated hidden window with nodeIntegration: true; the UI runs with nodeIntegration: false. Full plugin trust is preserved. (You are here.)
  2. Next — secure sandbox. We are designing a sandboxed execution model with an explicit, permissioned API for plugins. The goal is to keep plugins powerful while removing unrestricted Node.js/filesystem access by default.

When the sandbox lands, there will be a further, clearly documented migration with ample notice. The breaking changes above are intentionally minimal so that most plugins move forward unchanged.

Reporting issues

If a plugin breaks after this change and it isn't explained by one of the cases above, please open an issue with:

  • The plugin name/version and your Insomnia version.
  • What the plugin was doing when it failed.
  • Any error text shown in the UI or developer console.

We'll use these reports to refine both this interim phase and the upcoming sandbox design.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment