Mountebank Compatibility

Rift implements the Mountebank REST API and configuration format. This allows you to use Rift as a drop-in replacement for Mountebank with significantly better performance.

Scope: Rift imposters are HTTP/HTTPS only. Mountebank also supports tcp and smtp imposters, which Rift rejects — see the migration guide for the full compatibility table before you migrate. (This is separate from TCP fault injection, which HTTP imposters do support.)

New to the model? Start with Concepts — it explains imposters, stubs, predicates, responses, and behaviors conceptually, then the Rift-specific stateful features. This section is the syntax-level reference for the Mountebank-compatible surface.

Core Concepts

Imposters

An imposter is a mock server listening on a specific port. Each imposter:

  • Listens on a configurable port
  • Handles HTTP or HTTPS protocol
  • Contains one or more stubs for request matching

Stubs

A stub defines how to respond to matching requests:

  • Predicates: Rules to match incoming requests
  • Responses: What to return when predicates match

Predicates

Predicates define request matching criteria:

  • equals, deepEquals - Exact match
  • contains, startsWith, endsWith - Partial match
  • matches - Regex match
  • exists - Field existence check
  • inject - JavaScript function (requires --allowInjection)
  • jsonpath, xpath - Selectors that scope any of the above to part of a JSON or XML body
  • and, or, not - Logical combinations

Behaviors

Behaviors modify responses before sending:

  • wait - Add latency
  • repeat - Serve a response several times before moving to the next
  • copy - Copy request values to response
  • lookup - Look up a row in a CSV file
  • decorate - Transform response with JavaScript
  • shellTransform - Pipe the response through a shell command

Quick Example

Create an imposter with multiple stubs:

{
  "port": 4545,
  "protocol": "http",
  "name": "User Service Mock",
  "stubs": [
    {
      "predicates": [{
        "equals": { "method": "GET", "path": "/health" }
      }],
      "responses": [{
        "is": { "statusCode": 200, "body": "OK" }
      }]
    },
    {
      "predicates": [{
        "and": [
          { "equals": { "method": "GET" } },
          { "matches": { "path": "/users/\\d+" } }
        ]
      }],
      "responses": [{
        "is": {
          "statusCode": 200,
          "headers": { "Content-Type": "application/json" },
          "body": { "id": 1, "name": "User" }
        }
      }]
    },
    {
      "predicates": [{
        "equals": { "method": "POST", "path": "/users" }
      }],
      "responses": [{
        "is": {
          "statusCode": 201,
          "headers": { "Content-Type": "application/json" },
          "body": { "id": 999, "message": "Created" }
        },
        "_behaviors": {
          "wait": 100
        }
      }]
    }
  ]
}

REST API

Create Imposter 

POST /imposters
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http",
  "stubs": [...]
}

List Imposters 

GET /imposters

Get Imposter 

GET /imposters/{port}

Delete Imposter 

DELETE /imposters/{port}

Delete All Imposters 

DELETE /imposters

Documentation Sections

Table of contents