How to Run Insomnia Locally for Development: Complete Setup Guide

To run Insomnia locally for development, clone the Kong/insomnia repository, install Node.js ≥24 using fnm, run npm ci to install workspace dependencies, and execute npm run dev to start the Vite dev server and Electron application.

Insomnia is a monorepo-based Electron application maintained by Kong that uses npm workspaces, Vite, and electron-builder to manage its development workflow. The repository's package.json defines strict Node.js and npm version requirements, workspace configurations, and development scripts that spin up the dev server and launch Electron with hot-reloading. Below is a comprehensive guide to setting up the local development environment based on the actual source code configuration.

Prerequisites

Before running Insomnia locally, verify your system meets the version requirements specified in the root package.json.

Node.js and npm Versions

The engines field in the root package.json (package.json#L13-L16) requires:

• Node.js ≥ 24
• npm ≥ 11

These versions are mandatory because the bundled Electron 41.0.3 requires this specific Node runtime.

Version Manager Setup

Use fnm (Fast Node Manager) or another Node version manager to switch to the correct version. The repository includes a .nvmrc file that specifies the exact Node version required.

fnm use "$(cat .nvmrc)"

This command ensures you are running Node ≥ 24 before installing dependencies.

Clone and Install Dependencies

Clone the repository and install all workspace dependencies in one step.

git clone https://github.com/Kong/insomnia.git
cd insomnia
git checkout develop
fnm use "$(cat .nvmrc)"
npm ci

The npm ci command respects the workspaces array defined in the root package.json (package.json#L17-L26), installing dependencies for all packages under the packages/ directory. Do not use --ignore-scripts, as the postinstall script triggers install-libcurl-electron (package.json#L46) to install native libcurl bindings required by the application.

Development Scripts

The repository provides npm scripts to run Insomnia locally with different configurations.

Starting the Development Environment

Run the following command from the repository root:

npm run dev

This script (package.json#L27-L29) executes npm start -w insomnia, which launches both the Vite dev server and the Electron application. Alternatively, you can run npm start -w insomnia directly from the root.

Under the Hood

When you execute npm run dev, two processes start in parallel:

1. Vite dev server – The start:dev-server script runs vite dev (packages/insomnia/package.json#L32), launching the development server on port 3334 (configurable in packages/insomnia/package.json).

2. Electron main process – The start:electron script first builds entry points using esbuild.entrypoints.ts ([packages/insomnia/esbuild.entrypoints.ts](https://github.com/Kong/insomnia/blob/develop/packages/insomnia/esbuild.entrypoints.ts)), waits for the Vite dev server on port 3334, then launches Electron with debugging support: electron --inspect=5858 . (packages/insomnia/package.json#L33).

Auto-Restart Mode

For automatic restarts when files change, use:

npm run dev:autoRestart

This executes the start:autoRestart script (packages/insomnia/package.json#L31-L35), which monitors source files and restarts the Electron process without requiring manual intervention.

Build and Package

When you need to create production binaries rather than running in dev mode:

• Build only: npm run build compiles React Router routes and runs the custom build process (packages/insomnia/package.json#L22-L25).
• Package: npm run package builds the app then invokes electron-builder to produce installers for your current platform (packages/insomnia/package.json#L27).

# Build for production

npm run build

# Create distributable installer

npm run package

# Output appears in ./dist/

Troubleshooting Common Issues

Missing Native libcurl

If the postinstall script fails to install native dependencies, run it manually:

npm run install-libcurl-electron

Port Conflicts

The Vite dev server defaults to port 3334. If this port is occupied, change the dev-server-port value in packages/insomnia/package.json before starting the dev server.

Large Initial Build

The first run may be slow as TypeScript compilation and Vite bundling processes initialize all workspaces. Subsequent runs leverage cached builds and start significantly faster.

Summary

• Version requirements: Node ≥ 24 and npm ≥ 11 are mandatory, enforced via the engines field in root package.json.
• Workspace setup: Use npm ci to install dependencies across all workspaces defined in the monorepo structure.
• Development command: npm run dev starts the Vite server on port 3334 and launches Electron with debugging enabled.
• Key files: packages/insomnia/package.json contains start scripts, vite.config.ts configures the dev server, and esbuild.entrypoints.ts builds the Electron entry points.
• Production builds: Use npm run package to generate distributable binaries using electron-builder.

Frequently Asked Questions

What Node version do I need to run Insomnia locally?

You need Node.js version 24 or higher and npm version 11 or higher, as specified in the engines field of the root package.json. The repository includes a .nvmrc file, so running fnm use "$(cat .nvmrc)" will automatically switch to the correct version.

Why should I use npm ci instead of npm install?

Use npm ci to ensure exact dependency versions from package-lock.json are installed, and to ensure the postinstall script executes properly. The postinstall script installs native libcurl bindings required by the Electron application, which npm install might skip or handle differently.

What is the difference between npm run dev and npm run dev:autoRestart?

npm run dev starts the Vite dev server and Electron application once, requiring manual restart when you change main process code. npm run dev:autoRestart monitors files for changes and automatically restarts the Electron process, making it ideal when working on main process IPC handlers or entry points.

How do I fix issues with the Vite dev server not starting?

First, ensure port 3334 is available, or change the dev-server-port in packages/insomnia/package.json. Verify Node.js meets the version requirements (≥ 24), and check that npm ci completed without errors, particularly the install-libcurl-electron postinstall step. If problems persist, try running npm run start:dev-server separately to see Vite-specific error messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}