Insomnia REST Client: Setup and Best Practices (2026)

Insomnia is a free, open source (Apache 2.0) desktop API client from Kong for sending and testing HTTP/REST, GraphQL, gRPC, WebSocket, Socket.IO and Server-Sent Events (SSE) requests. The habits that make it pay off are: pick the right storage (Local Vault, Git Sync or Cloud Sync) before you start, put every URL and token in environment variables, and write after-response tests so a collection doubles as an API test suite you can run in CI with the Inso CLI. This guide covers those practices for Insomnia 13, the current major version as of October 2026.

What Insomnia is (and what changed in version 13)

Insomnia runs on macOS, Windows and Linux and is developed in the open at github.com/Kong/insomnia. Download it from insomnia.rest/download, or on macOS run brew install --cask insomnia.

Kong ships a major version twice a year and minor releases about every four weeks (Insomnia docs). Recent changes worth knowing, from the official changelog:

• 13.0 (June 2026): a tree-based sidebar, native Kong Konnect sync, and a switch of the template engine from Nunjucks to LiquidJS. Most templates work unchanged, but some tag syntax needs manual fixes after upgrading. Plugins also lost direct Node.js access, which broke some older plugins.
• 13.1 (July 2026): Git Sync projects can live anywhere on disk and read your ~/.gitconfig; first-class support for the HTTP QUERY method.
• 13.3 (September 2026): the old "Document" and "Collection" workspace types merged into one API Collection with Spec and Tests tabs, plus an opt-in sandboxed script engine.

If you follow an older tutorial and the menus don't match, this is why.

Best practice 1: choose storage deliberately

Every project in Insomnia has a storage type, and it decides where your requests (and anything secret inside them) end up (storage docs):

Storage	Where data lives	Use it when
Local Vault	Only on your machine	Solo work, sensitive APIs, company rules against cloud storage
Git Sync	A Git repository you control	Teams that want collections reviewed in pull requests next to the code
Cloud Sync	Kong's cloud	Quick sharing without managing a repo

For team work, Git Sync is usually the best choice: request changes show up as diffs, and the collection version matches the API version in the same branch. On the free Essentials plan, Git Sync is available for up to 3 users; Pro ($12 per user per month as of October 2026) removes that limit and raises mock requests from 1,000 to 10,000 per month (pricing). Collection runs are unlimited on all plans.

The Scratch Pad is a local workspace for quick, throwaway requests and needs no login; don't keep anything important there.

Best practice 2: organize requests like your API

• One collection per API or service, not per developer.
• Folders by resource (/users, /orders, /auth), mirroring your routes.
• Name requests by intent: Create order (valid), Create order (missing SKU → 400). Negative cases are as valuable as happy paths.
• Import instead of retyping: Insomnia imports OpenAPI specs, Postman collections, HAR files and cURL commands (paste a cURL command straight into the URL bar).

Best practice 3: put everything variable in environments

Hard-coded hosts and tokens are the most common Insomnia mistake. Insomnia has several environment levels (environments docs): global environments (shared by every collection in a project), collection environments, and folder environments. Each has a base environment and optional sub-environments (for example local, staging, production) that override base values.

When the same variable is defined in several places, Insomnia resolves it in this order:

1. Folder environment
2. Selected collection sub-environment
3. Collection base environment
4. Selected global sub-environment
5. Global base environment

A typical collection base environment:

{
  "base_url": "http://localhost:3000",
  "api_version": "v1"
}

And a staging sub-environment:

{
  "base_url": "https://staging.example.com"
}

Reference variables in any field, for example a URL of {{ _.base_url }}/{{ _.api_version }}/users. Press Ctrl+Space in a field to autocomplete variables and template tags.

Keep secrets out of synced data

• Mark a sub-environment as private: private environments are not synced or exported.
• For tokens and passwords, use secret variables. Generate a vault key first under Preferences > General > Security > Generate Vault Key. Secrets are stored encrypted locally and are only available in private global sub-environments. If you lose the vault key, the stored secrets are deleted.
• Enterprise plans can pull secrets from AWS, GCP, Azure or HashiCorp vaults instead.

Best practice 4: chain requests with scripts

Insomnia supports pre-request and after-response scripts written in JavaScript (scripting docs). The most common use is logging in once and reusing the token.

After-response script on a POST {{ _.base_url }}/auth/login request:

const body = insomnia.response.json();

insomnia.test('login succeeds', () => {
  insomnia.expect(insomnia.response.status).to.eql(200);
  insomnia.expect(body.token).to.be.a('string');
});

insomnia.environment.set('token', body.token);

Then set the Auth tab of other requests to Bearer Token with the value {{ _.token }}. Set auth on a folder once and let child requests inherit it instead of repeating it on every request.

Pre-request scripts are useful for timestamps, signatures or computed headers:

insomnia.environment.set('request_time', new Date().toISOString());

Scripts can read folder variables with insomnia.parentFolders.get('Orders').environment.get('order_id'), but only when the request is inside that folder.

Best practice 5: turn collections into tests

Every insomnia.test(...) block shows up in the Tests results and in the Collection Runner, which runs a folder or a whole collection in order, with optional iterations and CSV/JSON data files. Write at least one status assertion and one body assertion per request:

insomnia.test('returns the created order', () => {
  insomnia.expect(insomnia.response.status).to.be.oneOf([200, 201]);
  const order = insomnia.response.json();
  insomnia.expect(order.id).to.be.a('string');
});

Best practice 6: run the same collection in CI with Inso

The Inso CLI runs Insomnia collections and lints OpenAPI specs from a terminal or pipeline:

brew install inso          # macOS; Docker image: kong/inso
inso run collection "Orders API" --env "staging"
inso lint spec "Orders API"

With Git Sync, CI already has the collection files in the repository, so the pipeline tests exactly what's on the branch. Use a non-production environment and a dedicated test account for CI runs.

Other features worth using

• Mock servers to give frontend developers an endpoint before the backend exists (self-hosted or cloud-hosted).
• Code generation: right-click a request and generate a snippet for cURL, JavaScript fetch, Python and more.
• MCP client: Insomnia can connect to and debug MCP servers, which helps if you build tools for AI agents.
• Plugins for custom template tags and auth flows; check they support Insomnia 13 before installing.

Insomnia vs Postman and other alternatives

Insomnia and Postman cover similar ground: collections, environments, scripting, mocks and a CLI. Insomnia's main differences are that the desktop app is open source and that Local Vault and Git Sync let you keep data entirely off a vendor cloud. Postman has the larger ecosystem and public API network. For a feature and pricing breakdown, see Insomnia vs Postman.

If you want something lighter, Bruno stores collections as plain files in your repo and works offline, and Hoppscotch runs in the browser. More options are on our free Postman alternatives page and in the API tools category.

Limitations to know

• The free plan's Git Sync is capped at 3 users.
• Major releases can break plugins and template tags (13.0 did both); read the changelog before upgrading a team.
• Secret variables only live in private global sub-environments, which is less flexible than per-collection secrets.

FAQ

Is Insomnia a REST client?

Yes. Insomnia is a desktop REST API client, and it also supports GraphQL, gRPC, WebSockets, Socket.IO and Server-Sent Events. It adds environments, scripting, tests, mocks and OpenAPI design on top.

Is the Insomnia REST client free?

The app is open source under Apache 2.0, and the Essentials plan is $0 with unlimited local and cloud projects, unlimited collection runs, 1,000 mock requests per month and Git Sync for up to 3 users. Paid plans add more Git Sync users, mocks and enterprise controls.

What is the difference between Postman and Insomnia?

Both send and test API requests. Insomnia is open source and lets you store data locally or in your own Git repo; Postman is closed source, cloud-first and has a larger ecosystem. See the full comparison.

How do I download Insomnia for Windows?

Get the Windows installer from insomnia.rest/download. Installers are also available there for macOS and Linux.

Can I use Insomnia without uploading my data to the cloud?

Yes. Create projects with Local Vault storage (data stays on your device) or Git Sync (data goes only to the Git repository you choose), and use private environments and secret variables for credentials.