Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


GitHub Latest Release GitHub License Travis Docker Build Status Code Coverage (Codecov)

Documentation Website

YouTube Video Series

Bug Tracker


Stack Overflow

Faker API Reference


You've just found a new way of mocking microservices!

Control Plane

An example config that demonstrates the common features of Mockintosh:

  - name: Mock for Service1
    hostname: localhost
    port: 8000
    managementRoot: __admin  # open http://localhost:8001/__admin it in browser to see the UI  

      - path: "/"  # simplest mock

      - path: "/api/users/{{param}}"  # parameterized URLs
        response: "simple string response with {{param}} included"

      - path: /comprehensive-matching-and-response
        method: POST
          qName1: qValue  # will only match if query string parameter exists
          qName2: "{{regEx '\\d+'}}"  # will require numeric value
          x-required-header: someval  # will cause only requests with specific header to work
          text: "{{regEx '.+'}}"  # will require non-empty POST body
        response: # the mocked response specification goes below
          status: 202
          body: "It worked"
            x-response-header: "{{random.uuid4}}"  # a selection of random/dynamic functions is available
            x-query-string-value: "{{request.queryString.qName2}}"  # request parts can be referenced in response

Mockintosh is a service virtualization tool that's capable to generate mocks for RESTful APIs and communicate with message queues to either mimic asynchronous tasks or to simulate microservice architectures in a blink of an eye.

The state-of-the-art mocking capabilities of Mockintosh enables software development teams to work independently while building and maintaining a complicated microservice architecture.

Key features:

In this article we explain how and why Mockintosh was born as a new way of mocking microservices.

Quick Start

Install on MacOS

Install Mockintosh app on Mac using Homebrew package manager:

$ brew install up9inc/repo/mockintosh

Install on Windows

Download an installer from releases section and launch it. Follow the steps in wizard to install Mockintosh.

Install on Linux

Install Mockintosh Python package using pip (or pip3 on some machines):

$ pip install -U mockintosh

Use Demo Sample Config

Run following command to generate example.yaml file in the current directory:

$ mockintosh --sample-config example.yaml

then, run that config with Mockintosh:

$ mockintosh example.yaml

And open http://localhost:9999 in your web browser.

You can also issue some CURL requests against it:

curl -v http://localhost:8888/

curl -v http://localhost:8888/api/myURLParamValue123/action

curl -v "http://localhost:8888/someMoreFields?qName1=qValue&qName2=12345" -X POST -H"X-Required-Header: someval" --data "payload"

Command-line Arguments

The list of command-line arguments can be seen by running mockintosh --help.

If you don't want to listen all of the services in a configuration file then you can specify a list of service names (name is a string attribute you can set per service):

$ mockintosh example.yaml 'Mock for Service1' 'Mock for Service2'

Using --quiet and --verbose options the logging level can be changed.

Using --bind option the bind address for the mock server can be specified, e.g. mockintosh --bind

Using --enable-tags option the tags in the configuration file can be enabled in startup time, e.g. mockintosh --enable-tags first,second

OpenAPI Specification to Mockintosh Config Conversion (experimental)

Note: This feature is experimental. One-to-one transpilation of OAS documents is not guaranteed.

It could be a good kickstart if you have already an OpenAPI Specification for your API. Mockintosh is able to transpile an OpenAPI Specification to its own config format in two different ways:

CLI Option --convert

Using the --convert one can convert an OpenAPI Specification to Mockintosh config.

JSON output example:

$ wget
$ mockintosh swagger.json -c new_config.json json

YAML example:

$ mockintosh swagger.json -c new_config.yaml yaml

Automatic Conversion

If you start Mockintosh with a valid OpenAPI Specification file then it automatically detects that the input is an OpenAPI Specification file:

$ mockintosh swagger.json

and automatically starts itself from that file. Without producing any new files. So you can start to edit this file through the management UI without even restarting Mockintosh.

Build the Docs

Single-command from /docs to review docs locally:

docker run -p 8080:4000 -v $(pwd):/site bretfisher/jekyll-serve

Or manual:

Install Jekyll and Bundler:

$ gem install jekyll bundler

Install the gems:

$ cd docs/
$ bundle config set --local path 'vendor/bundle'
$ bundle install

Run the server:

$ bundle exec jekyll serve