insomnia Documentation

1. Project Overview & Quickstart (Kong/insomnia) Copy Chapter

File: README.md Copy Chapter

Insomnia API Client

Insomnia is an open-source, cross-platform API client for GraphQL, REST, WebSockets, Server-Sent Events (SSE), gRPC and any other HTTP compatible protocol.

With Insomnia you can:

• Debug APIs using the most popular protocols and formats.
• Design APIs using the native OpenAPI editor and visual preview.
• Test APIs using native test suites and collection runner.
• Mock APIs using a cloud or self-hosted mocking server.
• Build CI/CD pipelines using the native Insomnia CLI for linting and testing.
• Collaborate with others using the many collaboration features.
• And more including the ability to use 3rd party plugins.

The following storage options are supported for your Insomnia projects, collections, design specs and all other resources:

• Local Vault: for 100% local storage of collections, design specs and every other resource.
• Git Sync: for Git storage using any 3rd party Git repository, without going through the cloud.
• Cloud Sync: for cloud collaboration, optionally end-to-end encrypted (E2EE) in the cloud.

Get started for free Copy Chapter

Insomnia is available for Mac, Windows, and Linux and can be downloaded from the website:

https://insomnia.rest

Account & Subscriptions Copy Chapter

You can use Insomnia without an account with the local Scratch Pad, or you can create an account for free to get access to the full capabilities of the product.

Even with an account, Insomnia only stores your projects and files accordingly to the storage backend that you have selected, which can be Local Vault, Cloud Sync, Git Sync or any combination of them. As such - for example - you have the freedom to choose to store sensitive projects 100% locally or in a Git repository, while still being able to collaborate on others in the cloud. It's the best of both worlds.

For added security, Insomnia also offers a Private Environments feature, where your environments configuration is always stored locally and never in the cloud, independently from the storage option that you have chosen for your project.

Premium features and support Copy Chapter

Insomnia has a very generous free plan that will be satisfactory for most users, but if you need to get access to premium capabilities like unlimited collaboration, the Git Sync feature, the ability to create organizations for your projects, using a 3rd party IDP for logins (SAML, OIDC) and many other features, then you can explore the other subscription plans.

You can compare all subscription plans and get started for free.

Why does Insomnia require an account? Copy Chapter

Insomnia does not require an account if you decide to use the local Scratch Pad, but to access most capabilities of the product we require an account. Your account data is securely stored in compliance with ISO27001, SOC 2 Type II, ISO27018, Gold CSA STAR regulations and in accordance with our terms of service and privacy policy.

We require an account to sustainably build and improve the product, and to make sure we can continue to offer the many core capabilities in a free and open-source distribution. While open source software is free to use, it is unfortunately not free to build, and our ability to continue working on Insomnia is dependent on our ability to convert a subset of free users (that need premium features) to become paying customers of our product.

If you are a user that cannot share API data like collections and design specifications to the cloud, this is still possible by selecting "Local Vault" as the storage of your Insomnia projects: having an Insomnia account is not tied to how you wish to store your sensitive API data (which can be stored 100% locally via Local Vault, on a 3rd party Git repository without any cloud storage via Git Sync, or in the cloud for ease of collaboration via Cloud Sync).

Bugs and Feature Requests Copy Chapter

Have a bug or a feature request? First, read the
issue guidelines and search for existing and closed issues. If your problem or idea is not addressed yet, please open a new issue.

For more generic product questions and feedback, join the Slack Team.

Contributing Copy Chapter

Please read through our contributing guidelines and code of conduct. Included are directions for opening issues, coding standards, and notes on development.

Documentation Copy Chapter

Check out our official Insomnia Documentation.

Develop Insomnia Copy Chapter

Development on Insomnia can be done on Mac, Windows, or Linux as long as you have Node.js and Git. See the .nvmrc file located in the project for the correct Node version.

Initial Dev Setup

This repository is structured as a monorepo and contains many Node.JS packages. Each package has its own set of commands, but the most common commands are available from the root package.json and can be accessed using the npm run … command. Here are the only three commands you should need to start developing on the app.

# Install and Link Dependencies
npm i

# Run Lint
npm run lint

# Run type checking
npm run type-check

# Run Tests
npm test

# Start App with Live Reload
npm run dev

# Start App with both renderer process live reload and main process auto restart
npm run dev:autoRestart

Linux Copy Section

If you are on Linux, you may need to install the following supporting packages:

Ubuntu/Debian

# Update library
sudo apt-get update

# Install font configuration library & support
sudo apt-get install libfontconfig-dev

Fedora

# Install libcurl for node-libcurl
sudo dnf install libcurl-devel

Also on Linux, if Electron is failing during the install process, run the following

# Clear Electron install conflicts
rm -rf ~/.cache/electron

Windows Copy Section

If you are on Windows and have problems, you may need to install Windows Build Tools

Editor Requirements

You can use any editor you'd like, but make sure to have support/plugins for the following tools:

• ESLint - For catching syntax problems and common errors
• JSX Syntax - For React components

Develop Inso CLI Copy Chapter

• npm i
• Start the compiler in watch mode: npm run inso-start
• Run: ./packages/insomnia-inso/bin/inso -v

Plugins Copy Chapter

Search for, discover, and install plugins from the Insomnia Plugin Hub!

Community Projects Copy Chapter

• Insomnia Documenter - Generate beautiful API documentation pages using the documenter plugin or your Insomnia export file.
• GitHub API Spec Importer - A complete set of GitHub REST API route specifications that can be imported straight into Insomnia.
• Swaggymnia - Generate Swagger documentation for your existing API in Insomnia.

License Copy Chapter

Apache-2.0 © Insomnia

File: packages/insomnia-smoke-test/playwright/pages/README.md Copy Chapter

Playwright POM Conventions

This directory contains the Insomnia smoke-test Page Object Model (POM).
The goal is to keep tests stable, readable, and selector-safe.

1. Object Definitions Copy Chapter

• InsomniaApp: root facade. It wires page objects and shared components.
• Page object: route-level surface (for example, project page).
• Component object: reusable or bounded UI region (for example, statusbar, tabbar, sidebar).

2. Page vs Component Split Copy Chapter

• Put route-specific workflows in a Page object.
• Put reusable or independently testable UI regions in a Component.
• A Page composes its own components.
• InsomniaApp composes top-level pages/components and exposes shortcuts.
• Tests should use POM APIs first. Raw page.getBy... is only acceptable for gaps that are not modeled yet.

3. Locator Ownership and Naming Copy Chapter

• Every page/component must have its own root getter.
• Every POM must manage all locators used by its own actions.
• Use xxxLocator(...) method naming when the locator needs parameters (for example, list row by name).
• For a single fixed element (for example, root, plusButton), expose it as a getter directly.
• Scope locators from root whenever possible to reduce collisions.
• If a locator belongs to an existing POM, tests should not duplicate that selector.

4. API Naming Copy Chapter

• Action methods use verb-first names: closeTab, openAddTabMenu.
• POM exposes actions and locators; assertions stay in test files.
• Keep methods focused on one behavior.

5. Test Usage Pattern Copy Chapter

Instantiate once per test and use composed objects:

test('example test', async ({ insomnia }) => {
  await insomnia.projectPage.createCollection();
  await insomnia.tabbar.closeTab('New Request');
  await expect.soft(insomnia.tabbar.tabLocator('foo')).toHaveAttribute('data-selected', 'true');
});

File: packages/insomnia-smoke-test/README.md Copy Chapter

Insomnia Smoke Tests

Playwright E2E tests for the Insomnia desktop app.

CLI smoke tests: CLI.md

Test structure Copy Chapter

tests/
  smoke/      # Main suite — runs on every CI push (Ubuntu only)
  critical/   # Single critical-path test — runs on release
  migration/  # Data migration tests

All commands below must be run from the repo root.

Quick-start Copy Chapter

npm install
npm run test:smoke:dev   # run all Smoke tests (dev mode)

Both the echo server (port 4010) and the Vite dev server start automatically.

Filter to one test — pass a substring of the test title or file name:

npm run test:smoke:dev -- oauth

Interactive UI:

npm run test:smoke:dev -- --ui

Step-through debugger:

PWDEBUG=1 npm run test:smoke:dev

Additional log levels Copy Chapter

DEBUG=pw:api npm run test:smoke:dev         # Playwright API logs
DEBUG=pw:browser npm run test:smoke:dev     # Insomnia console logs
DEBUG=pw:WebServer npm run test:smoke:dev   # Web server logs

Traces and error context Copy Chapter

On failure, two artifacts are written under packages/insomnia-smoke-test/traces/<test-name>/:

• error-context.md — error details, ARIA page snapshot at point of failure, and annotated test source. Read this first.
• trace.zip — full Playwright trace (network, screenshots, DOM snapshots).

Open a trace:

npx playwright show-trace packages/insomnia-smoke-test/traces/<test-name>/trace.zip

Or upload to trace.playwright.dev.

CI traces are available as artifacts on failed workflow runs.

Build / package modes Copy Chapter

Run against a JS bundle (build) or a packaged binary (package) instead of the dev watcher:

# build mode
npm run app-build
npm run test:smoke:build

# package mode
npm run app-package
npm run test:smoke:package

macOS package mode: set com.apple.security.cs.disable-library-validation to true in entitlements.mac.inherit.plist to allow unsigned local binaries. Do not commit this change.

Non-CI / pre-release tests Copy Chapter

npm run test:dev -w insomnia-smoke-test -- tests/smoke/preferences-interactions.test.ts

Cert refresh Copy Chapter

If the custom CA cert test fails after 2026:

mkcert -install && mkcert localhost && mkcert -CAROOT

File: packages/insomnia-inso/README.md Copy Chapter

Documentation

How to use Inso CLI.

Testing Copy Chapter

# unit tests
npm run test:unit

# start smoke test api (required for e2e tests)
npm run serve -w insomnia-smoke-test

# e2e tests for dev bundle
npm run test:bundle

# e2e tests for binary
npm run test:binary

Development Copy Chapter

Getting started Copy Section

npm run inso-start
npm run test -w insomnia-inso
# will default to insomnia app database
$PWD/packages/insomnia-inso/bin/inso run test
# will use config, useful for testing with fewer args
$PWD/packages/insomnia-inso/bin/inso -w packages/insomnia-inso/src/db/fixtures/git-repo script runTest

node-libcurl Copy Section

Error: The module '.../insomnia/node_modules/@getinsomnia/node-libcurl/lib/binding/node_libcurl.node' was compiled against a different Node.js version using

node-libcurl builds for 3 operating systems and two versions of nodejs. insomnia-inso uses the nodejs build and insomnia app uses the electron build. you can switch between them using the following two commands

# install node version
npm run install-libcurl-node
# install electron version
npm run install-libcurl-electron

Run CLI Smoke Tests Copy Chapter

# Run CLI tests
npm run test:bundle -w insomnia-inso
# Package the Inso CLI binaries
npm run inso-package
npm run test:binary -w insomnia-inso

Debugging CLI tests using watcher Copy Chapter

This is helpful for debugging failing api tests

From project root, in separate terminals:

# start smoke test api
npm run serve -w insomnia-smoke-test

# watch inso
npm run start -w insomnia-inso

# run api test with dev bundle. To debug run this in a Javascript Debug Terminal in VSCode
$PWD/packages/insomnia-inso/bin/inso run test "Echo Test Suite" -w $PWD/packages/insomnia-smoke-test/fixtures/inso-nedb --env Dev --verbose

How to debug pkg Copy Chapter

# run modify package command and then a unit test
npm run package -w insomnia-inso && \
$PWD/packages/insomnia-inso/binaries/inso run test "Echo Test Suite" -w $PWD/packages/insomnia-smoke-test/fixtures/inso-nedb --env Dev --verbose

How to update the `inso-nedb` fixtures Copy Chapter

Run Insomnia with INSOMNIA_DATA_PATH environment variable set to fixtures/inso-nedb, e.g.:

INSOMNIA_DATA_PATH=packages/insomnia-smoke-test/fixtures/inso-nedb /Applications/Insomnia.app/Contents/MacOS/Insomnia

Relaunch the app one more time, so that Insomnia compacts the database.

The .gitignore file will explicitly ignore certain database files, to keep the directory size down and avoid prevent sensitive data leaks.

How to run inso with the `inso-nedb` fixture locally? Copy Chapter

Set the -w argument pointed to packages/insomnia-smoke-test/fixtures/inso-nedb:

# if installed globally
inso -w 

# using the package bin
./packages/insomnia-inso/bin/inso -w 

# using a binary
./packages/insomnia-inso/binaries/insomnia-inso -w

How to debug the bundled assets Copy Chapter

DEBUG=1 npm run build

This will generate an artifacts directory containing information about the bundled assets.
The meta.json can be uploaded to https://esbuild.github.io/analyze/ to visualize the bundle.
The bundle-analysis.log can be used to see the dependency tree of the bundle.

How to generate documents about inso Copy Chapter

1. Ensure your node version matches the project .nvmrc perhaps with fnm use or another version manager.
2. Run the script below, which will build inso in dev mode in order to use it to generate docs about itself
3. The docs appear in your vscode diff, or you can look in ./packages/insomnia-inso/reference/ if the version number looks wrong you might need to check what branch you're on, it should be run from develop ideally as the only changes in the release branch should be hotfixes that dont affect inso docs

npm i && npm run build -w insomnia-inso && $PWD/packages/insomnia-inso/bin/inso generate-docs

File: packages/insomnia-component-docs/docs/Components/banner.mdx Copy Chapter

id: banner sidebar_label: 'Banner' sidebar_position: 1 Copy Chapter

Banner

Props Copy Chapter

Usage Examples Copy Chapter

Info Copy Section

Info without title Copy Section

Warning Copy Section

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-font: Banner text color
• --color-surprise: Info banner background
• --color-warning: Warning banner background

You can customize these variables in your CSS to theme the banner appearance.

File: packages/insomnia-component-docs/docs/Components/button.mdx Copy Chapter

id: button sidebar_label: 'Button' sidebar_position: 1 Copy Chapter

Button

A flexible button component built on React Aria's Button component with multiple variants, sizes, and states.

Props Copy Chapter

Extends all React Aria ButtonProps.

Usage Examples Copy Chapter

Different Sizes Copy Section

function Buttons() {
  return (
    
      
        Click Me
      
      
        Click Me
      
      
        Click Me
      
    
  );
}

Different types Copy Section

function Buttons() {
  return (
    
      
        primary
      
      
        danger
      
      default
      text
    
  );
}

Disabled Copy Section

function Buttons() {
  return (
    
      
        primary
      
      
        danger
      
      default
      
        text
      
    
  );
}

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-font: Default button text color
• --color-font-surprise: Primary button text color
• --color-font-danger: Danger button text color
• --color-bg: Button background color (default)
• --color-surprise: Primary button background color
• --color-danger: Danger button background color
• --hl: Default border color (outlined)
• --hl-xs: Subtle highlight (hover, pressed, focus)

You can customize these variables in your CSS to theme the button appearance.

File: packages/insomnia-component-docs/docs/Components/checkbox.mdx Copy Chapter

id: checkbox sidebar_label: 'Checkbox' sidebar_position: 4 Copy Chapter

Checkbox

A flexible checkbox component built on React Aria's Checkbox component with support for individual checkboxes and checkbox groups. Features indeterminate state, custom styling, and full accessibility support.

Checkbox Props Copy Chapter

Extends all React Aria CheckboxProps.

CheckboxGroup Props Copy Chapter

Extends all React Aria CheckboxGroupProps.

Usage Examples Copy Chapter

Basic Checkbox Copy Section

<Checkbox>Accept terms and conditions</Checkbox>

Default Selected Copy Section

<Checkbox defaultSelected={true}>Remember me</Checkbox>

Disabled State Copy Section

<Checkbox isDisabled>This option is not available</Checkbox>

CheckboxGroup Copy Section

<CheckboxGroup
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
  ]}
/>

Select All Pattern Copy Section

function SelectAll() {
  const allOptions = [
    { label: 'Feature A', value: 'a' },
    { label: 'Feature B', value: 'b' },
    { label: 'Feature C', value: 'c' },
  ];

  const [selectedFeatures, setSelectedFeatures] = useState(['a']);

  const allSelected = selectedFeatures.length === allOptions.length;
  const someSelected = selectedFeatures.length > 0 && !allSelected;

  const handleSelectAll = (checked: boolean) => {
    if (checked) {
      setSelectedFeatures(allOptions.map(opt => opt.value));
    } else {
      setSelectedFeatures([]);
    }
  };

  return (
    
      <Checkbox isSelected={allSelected} isIndeterminate={someSelected} onChange={handleSelectAll}>
        Select All Features
      </Checkbox>

      <hr className="my-2" />

      <CheckboxGroup value={selectedFeatures} onChange={setSelectedFeatures} options={allOptions} />
    
  );
}

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-font: Checkbox text color
• --hl-sm: Standard border color
• --hl-xs: Highlight for hover/selected/indeterminate
• --color-success: Checkmark color

You can customize these variables in your CSS to theme the checkbox appearance.

Checkbox vs Switch Copy Chapter

File: packages/insomnia-component-docs/docs/Components/input.mdx Copy Chapter

id: input sidebar_label: 'Input' sidebar_position: 1 Copy Chapter

Input

A flexible text input component built on React Aria's Input component with consistent styling and accessibility features.

Props Copy Chapter

Extends all React Aria TextFieldProps.

Usage Examples Copy Chapter

Default Input Copy Section

With Label Copy Section

With Default Value Copy Section

Disabled State Copy Section

Read-Only State Copy Section

Password Input Copy Section

Search Input Copy Section

function SearchInputDemo() {
  const [searchQuery, setSearchQuery] = useState('');

  return ;
}

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-bg: Input background color
• --hl-sm: Standard border color
• --hl-lg: Highlight for focus/active
• --color-danger: Error/invalid state color

You can customize these variables in your CSS to theme the input appearance.

File: packages/insomnia-component-docs/docs/Components/input-number.mdx Copy Chapter

id: input-number sidebar_label: 'Input Number' sidebar_position: 2 Copy Chapter

Input Number

A numeric input component with optional increment/decrement buttons (steppers) built on React Aria's NumberField & Input component.

Props Copy Chapter

Extends all React Aria NumberFieldProps.

Usage Examples Copy Chapter

Basic Number Input Copy Section

With Label Copy Section

Increase/Decrease Stepper Copy Section

The step prop defines how much the value changes per click.

With Min and Max Constraints Copy Section

Values outside this range will trigger the invalid state.

Decimal Numbers Copy Section

Percentage Input Copy Section

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-bg: InputNumber background color
• --color-font: InputNumber text color
• --hl-sm: Standard border color
• --hl-md: Highlight for focus/active
• --color-danger: Error/invalid state color

You can customize these variables in your CSS to theme the input number appearance.

File: packages/insomnia-component-docs/docs/Components/link.mdx Copy Chapter

id: link sidebar_label: 'Link' sidebar_position: 1 Copy Chapter

LearnMoreLink

An external link component with an arrow icon that opens in a new tab.

Props Copy Chapter

Usage Examples Copy Chapter

Basic Link Copy Section

<LearnMoreLink href="https://docs.insomnia.rest">Learn more about Insomnia</LearnMoreLink>

Custom Styling Copy Section

<LearnMoreLink className="text-[--color-font]!" href="https://insomnia.rest">
  Visit our website
</LearnMoreLink>

Styling Copy Chapter

CSS Variables Copy Section

The component uses the following CSS variables for theming:

• --color-font: Link text color
• --color-bg: Link background color

You can customize these variables in your CSS to theme the link appearance.

2. Official Technical Reference & Guides (Kong/insomnia-docs) Copy Chapter

Insomnia Documentation

Welcome to the open-source Insomnia documentation repository. Find the Insomnia documentation site at docs.insomnia.rest.

Please refer to our Contributing Guidelines.

Run locally Copy Chapter

1. Clone the repository.
2. Install Ruby and Bundler.
3. Run cd docs.
4. Run bundle install.
5. Run bundle exec jekyll serve.
6. Browse to http://localhost:4000.

Run with Docker Copy Chapter

1. Clone the repository.
2. Install Docker.
3. Run make build or docker build --tag insomnia-docs:latest ..
4. Run make run or docker run --rm -it -p 4000:4000 -v ${PWD}/docs:/docs insomnia-docs:latest.
5. Browse to http://localhost:4000.

Run with nix Copy Chapter

1. Clone the repository.
2. Install Nix.
3. cd docs
4. nix-shell
5. bundle install
6. bundle exec jekyll serve -H 0.0.0.0 -P 4000 --watch