# How to Run Insomnia Locally for Development: Complete Setup Guide

> Run Insomnia locally for development with this complete setup guide. Clone the repo, install Node JS, manage dependencies with npm ci, and start the app with npm run dev.

- Repository: [Kong/insomnia](https://github.com/Kong/insomnia)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/package.json).

### Node.js and npm Versions

The `engines` field in the root [`package.json`](https://github.com/Kong/insomnia/blob/main/package.json) ([`package.json#L13-L16`](https://github.com/Kong/insomnia/blob/develop/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.

```bash
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.

```bash
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`](https://github.com/Kong/insomnia/blob/main/package.json) ([`package.json#L17-L26`](https://github.com/Kong/insomnia/blob/develop/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`](https://github.com/Kong/insomnia/blob/develop/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:

```bash
npm run dev

```

This script ([`package.json#L27-L29`](https://github.com/Kong/insomnia/blob/develop/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`](https://github.com/Kong/insomnia/blob/develop/packages/insomnia/package.json#L32)), launching the development server on port **3334** (configurable in [`packages/insomnia/package.json`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json)).

2. **Electron main process** – The `start:electron` script first builds entry points using [`esbuild.entrypoints.ts`](https://github.com/Kong/insomnia/blob/main/esbuild.entrypoints.ts) ([[`packages/insomnia/esbuild.entrypoints.ts`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/develop/packages/insomnia/package.json#L33)).

### Auto-Restart Mode

For automatic restarts when files change, use:

```bash
npm run dev:autoRestart

```

This executes the `start:autoRestart` script ([`packages/insomnia/package.json#L31-L35`](https://github.com/Kong/insomnia/blob/develop/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`](https://github.com/Kong/insomnia/blob/develop/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`](https://github.com/Kong/insomnia/blob/develop/packages/insomnia/package.json#L27)).

```bash

# 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:

```bash
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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/packages/insomnia/package.json) contains start scripts, [`vite.config.ts`](https://github.com/Kong/insomnia/blob/main/vite.config.ts) configures the dev server, and [`esbuild.entrypoints.ts`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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`](https://github.com/Kong/insomnia/blob/main/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.