Designing Insomnia Environments: Base Defaults, Overrides, and Where Secrets Actually Live

If you maintain an API collection in Insomnia that more than one person runs, the recurring problem is hard-coded values: a developer exports the collection, the staging token ships with it, and someone hits production from a laptop that thought it was pointing at dev. Insomnia's environment system exists to solve exactly this. This note covers the requirements it addresses, the smallest design that works, where the trust boundaries sit, and the failure modes you'll actually hit.

The behavior described here reflects Insomnia's long-standing environment model (base environment plus sub-environments, with {{ _.variable_name }} templating). UI details vary across versions, so verify against your installed release before relying on specifics.

Requirements the design must satisfy

A workable environment layer for a REST client has four jobs:

1. Let one request definition run against multiple deployment stages (dev, staging, prod) without editing the request.
2. Keep per-developer and per-stage secrets out of the shared collection export.
3. Make the resolved value visible before the request is sent, so mistakes are caught in the UI, not in a server log.
4. Fail loudly enough that a missing variable is noticed, but not so loudly that exploratory work is blocked.

The smallest suitable design: base plus overrides

Insomnia's model is a two-level hierarchy. The Base Environment holds defaults that apply everywhere. Each named sub-environment (e.g., "Development", "Production") is a sparse override layer: it only needs to define the keys that differ. Resolution is sub-environment first, then base, then undefined.

A minimal setup looks like this. Base environment:

{
  "api_host": "api.dev.example.com",
  "scheme": "https",
  "timeout_ms": 5000
}

Production sub-environment:

{
  "api_host": "api.example.com",
  "timeout_ms": 10000
}

Requests then reference values with template syntax, e.g. a URL of {{ _.scheme }}://{{ _.api_host }}/v1/users. Switching the active environment in the UI re-resolves every template in real time — the request editor shows the interpolated result, which is your primary operational check.

Resist the urge to add more layers. Folder-level environments and deeply nested variable references (a variable whose value contains another {{ }} tag) are supported, but each extra indirection makes "what value will this request actually send?" harder to answer. Two levels covers most teams.

Trust and data boundaries

The key boundary: the request definition and the environment data are stored separately. When you export or sync a collection, the intent is that requests travel but secrets don't. In practice this boundary is only as strong as your discipline:

• Sub-environments can be included in exports depending on your export/sync choices. Treat any environment containing real credentials as non-shareable, and audit exports before sending them.
• Environment values are stored as plain text on disk. Insomnia is not a secrets manager. For genuinely sensitive tokens, reference a placeholder and paste the real value into a private environment that never leaves your machine, or rotate tokens on a schedule that assumes the file could leak.
• Shared team environments should contain only non-secret configuration: hosts, ports, feature flags, timeouts.

Operational checks

Two checks catch most problems before a request is sent:

1. Hover/preview the resolved template. With an environment active, the UI shows the interpolated value of a templated field. If you see a literal {{ _.api_host }} or an empty segment in the URL (e.g., https:///v1/users), the variable didn't resolve.
2. The two-environment switch test. Create Dev and Prod environments with the same key and different values, then switch between them and confirm the request URL changes. This validates both the override hierarchy and that you're referencing the right key name. It takes two minutes and catches typos that silently fall back to base.

Failure modes

The most dangerous mode is the silent one: an undefined variable interpolating to an empty string rather than an error. A request to https://{{ _.host }}/admin with a missing host becomes a malformed request at best. Build the habit of glancing at the resolved preview before sending anything destructive.

What would change this design

The local, manually-switched model starts to strain when:

• Team-wide real-time sync is required. If variable updates must propagate to teammates without re-export or manual refresh, you need a cloud-synced environment store with conflict semantics — a different architecture, not a tweak.
• Secrets must rotate centrally. Once compliance requires short-lived credentials, environment JSON should hold references to an external secrets manager rather than values, and the client needs a fetch-at-send-time integration.
• CI runs the collection. Headless execution (e.g., via Insomnia's CLI tooling, where available in your version) needs environments injected as files or env vars, which pushes you toward generating environment JSON from your deployment pipeline instead of hand-editing it in the UI.

Until one of those is true, the base-plus-override hierarchy with secrets kept in a private, never-exported environment is the right size. Verify it works by running the two-environment switch test after any structural change — it's cheap and it exercises the entire resolution path.