Insomnia Mockbin: the API mock server behind Insomnia, and its licence contradiction

Insomnia Mockbin exists as the backend for Insomnia's mock feature, not as a standalone library

Insomnia Mockbin is Kong's own implementation of the API mock service embedded in Insomnia, the API client. The repository description makes the relationship explicit: it is the underlying backend for the API mocks capability of Insomnia. This means the intended users are teams deploying a self-hosted Insomnia instance, not developers looking for a general-purpose mock server to include in their own projects.

Kong also maintains the open-source Kong Gateway and Insomnia itself, both under the Kong organisation on GitHub. Mockbin sits alongside those projects but is governed by different terms. The distinction between Insomnia-the-API-client and Mockbin-the-mock-backend matters if you need to file a bug: the README points to the Kong Insomnia Mockbin issues page for bugs and feature requests, not to the main Insomnia repository.

The project handles incoming HTTP requests, stores them according to the HAR format, and returns configurable responses. Its purpose is to let Insomnia users define what a mock endpoint returns without spinning up a real API. The four output formats, the Redis-backed storage and the HAR schema are all choices that serve that specific use case.

HAR-format storage, Redis-backed bins, and four response output types

Every request Mockbin receives is stored as a HAR (HTTP Archive) record. HAR is a JSON-based format for recording HTTP transactions that originated in browser developer tools, and using it as the internal storage schema means the recorded data is already in a format that debugging tools and API documentation generators can consume.

The server stores these records in Redis, keyed to a bin identifier. Bins are the core data structure: a bin collects all requests that match its path, and the response it returns is configurable per bin. Redis handles expiry through the MOCKBIN_REDIS_EXPIRE_SECONDS environment variable, which the docker-compose.yml sets to 1000000000 seconds by default. At that value, bins persist well past any practical session length, which is effectively indefinite storage for most deployments.

Response output format is controlled per request. The server supports JSON, YAML, XML and HTML. Proxy compatibility is handled via the X-Forwarded-For, X-Forwarded-Host and similar headers, so IP resolution works correctly when Mockbin sits behind a load balancer or reverse proxy. HTTP Method Override lets a client send a request with one method while specifying another via the X-HTTP-Method-Override request header or through the _method query string parameter, which accommodates clients that cannot send PUT or DELETE requests directly.

Running locally: Redis on 6379, fnm for Node version, and three startup modes

The local setup requires Redis running before the server starts. On macOS, the two-command path is:

brew install redis
brew services start redis

Redis listens on localhost:6379 by default. After that, clone the repository, copy the sample environment file, and install the Node.js version the project specifies:

git clone https://github.com/Kong/mockbin.git ./mockbin
cd mockbin
cp .env.sample .env
brew install fnm
fnm use
npm install

Node version management is also supported through nvm, n or volta as alternatives to fnm. The project requires Node.js version 22.13.0 or higher, which is set in the engines field of package.json. After that, three startup modes are available:

npm start
# OR watch for changes
npm run dev
# OR with debug logs
DEBUG=mockbin npm run dev

The .env.sample file shows the four configurable variables: MOCKBIN_PORT defaults to 8080, MOCKBIN_QUIET to false, MOCKBIN_REDIS to redis://127.0.0.1:6379, and MOCKBIN_REDIS_EXPIRE_SECONDS to 1000000000. Running with Docker Compose is a simpler alternative: `docker compose up` brings up both the app and a Redis container, with the app wired to redis://redis:6379 inside the compose network.

The package.json terms field conflicts with the README's source-visible notice

The README opens with a notice in bold: this repository is source visible, but not open-source, and it directs readers to check the terms file before using the software. GitHub's automatic recogniser cannot classify what the terms file contains, so the project appears in metadata as a custom type rather than a standard identifier.

The package.json tells a different story. Its terms field contains a value that is a standard permissive identifier commonly associated with broad reuse rights. That field is set at the package level, not in a derived or inherited configuration, and it directly contradicts the README's source-visible claim.

This conflict is not a minor inconsistency. The README's source-visible notice is a deliberate restriction, while the package.json entry is a historical artefact or an oversight. Read the full terms document at the repository root before running or distributing the code. The last push was on 2026-10-02, and Kong is the maintainer, so asking Kong directly is the appropriate step when the terms are unclear for a given use case.

Bins stop functioning silently when Redis is unreachable

A specific warning in the repository covers what happens when Redis is not running: Mockbin will start without Redis, but you will not be able to set or get response bins. The word "silently" does not appear there, but the implication is that the server process comes up, listens on its port and appears healthy while the core feature is broken.

This matters most in Docker deployments where the startup order is not guaranteed. If Mockbin starts before Redis is ready, the application will accept requests but bins will not persist or respond as configured. The docker-compose.yml file does not include a healthcheck or a depends_on condition that waits for Redis to be healthy before starting the app container. The MOCKBIN_REDIS environment variable points to the Redis address, so verifying that address is reachable before routing traffic to Mockbin is the right first check when debugging an empty mock response.

For the same reason, any Redis outage after startup will break bins without taking down the application. A monitoring setup that checks bin creation and retrieval rather than just the HTTP port will catch this failure mode where a health check on port 8080 alone will not.

Two container registries, cosign signatures, and SLSA provenance attestations

Kong publishes two separate Docker images for different deployment contexts. The cloud-hosted variant lives at ghcr.io/kong/insomnia-mockbin-cloud, used when Kong manages the infrastructure. The self-hosted variant is at ghcr.io/kong/insomnia-mockbin-self-hosted, intended for teams running their own Insomnia deployment. The Dockerfile uses a Chainguard Node base image pinned by SHA256 digest for supply chain security.

Both images are signed using cosign, with signatures published to the GitHub Container Registry. Verification uses the OIDC issuer at https://token.actions.githubusercontent.com and the workflow path in the .github/workflows/ directory as the expected certificate identity. The workflow name is the identity anchor in the certificate, not a runtime endpoint.

SBOM files (Software Bills of Materials) are produced for both Docker container images and the source code repository. They are attached to version tags on the repository and also available from GitHub's CI workflow output. SLSA Level 3 build provenance is generated for container images and can be verified using cosign or slsa-verifier against attestations in the GitHub Container Registry.

Version 2.1.3 in package.json versus v2.0.2 as the most recent formal package

There is a gap between the version in package.json and what has been formally packaged. The package.json sets the version to 2.1.3, and the most recent formal package on GitHub is v2.0.2 from 2024-07-01. That means at least three patch increments have been merged to the main branch without a corresponding public package. For anyone consuming the project through the npm package or by pulling a versioned Docker image, the working tree is ahead of what is formally available.

This is common in projects where the internal development cycle outpaces the formal package cadence, but it creates a gap for teams that want to pin to a known version. The package.json identifies the npm package name as mockbin, not insomnia-mockbin, which is the project's GitHub name. Anyone searching npm for insomnia-mockbin would not find it under that name.

Kong documents the available deployment options at developer.konghq.com/insomnia/mock-servers/ and the self-hosted options at the Insomnia self-hosted documentation. Those are the appropriate starting points for deciding whether to run this server rather than using Kong's cloud-managed version.

Editorial conclusion

Use Insomnia Mockbin if you are running a self-hosted Insomnia installation and need the mock server backend that the API client depends on. It is not appropriate for embedding in your own product or redistributing without first reading the terms document at the repository root, because the README and the package.json conflict on what is permitted. Before deploying with Docker, verify that MOCKBIN_REDIS points to a reachable Redis instance, because the server starts without it but bins will not function. Also confirm the Node.js version on the target host: the engines field requires 22.13.0 or higher, and older Node installations will not run the server.

Frequently asked questions

Official sources

1. Issues
2. Kong/insomnia-mockbin on GitHub
3. Project website
4. README
5. Releases