Migrating from Mountebank to Rift

Rift is designed to run your Mountebank setup unchanged. This guide covers the migration and the differences worth checking against your tests.

---

Compatibility Overview

Rift is compatible with Mountebank 2.9.5, the latest release (@mbtest/mountebank). It maintains full compatibility with Mountebank's HTTP/HTTPS protocol support:

Feature	Mountebank	Rift	Notes
HTTP Imposters	Yes	Yes	Fully compatible
HTTPS Imposters	Yes	Yes	Fully compatible
REST API	Yes	Yes	Same endpoints
JSON Configuration	Yes	Yes	Same format
All Predicates	Yes	Yes	equals, contains, matches, exists, etc.
JSONPath	Yes	Yes	Same syntax; the jsonpath-plus shorthands .[ and a 0 slice end are read as Mountebank reads them
XPath	Yes	Yes	Same syntax
Behaviors	Yes	Yes	wait, repeat, copy, lookup, decorate, shellTransform — on is, inject and proxy responses, in Mountebank's order
Proxy Mode	Yes	Yes	Record and replay; an omitted mode is proxyOnce in both. Rift refuses an unknown mode; Mountebank treats it as proxyOnce
Injection	Yes	Yes	JavaScript functions
TCP Protocol	Yes	No	protocol must be http/https; a tcp imposter is rejected
SMTP Protocol	Yes	No	Not supported; an smtp imposter is rejected

---

Migration Steps

Step 1: Replace the Docker Image

If using Docker, simply change the image:

# Before (Mountebank)
services:
  mountebank:
    image: bbyars/mountebank:2.9.2
    ports:
      - "2525:2525"
    command: ["start", "--allowInjection"]

# After (Rift)
services:
  rift:
    image: zainalpour/rift-proxy:latest
    ports:
      - "2525:2525"
    environment:
      - MB_ALLOW_INJECTION=true

Step 2: Use Your Existing Configuration

Rift reads Mountebank configuration files directly:

# Mountebank
mb start --configfile imposters.json

# Rift
docker run -v $(pwd)/imposters.json:/imposters.json \
  zainalpour/rift-proxy:latest --configfile /imposters.json

# Rift binary (same command line as Mountebank)
rift start --configfile imposters.json

Step 3: Update Environment Variables

Map Mountebank CLI options to Rift environment variables:

Mountebank CLI	Rift Environment Variable
--port 2525	MB_PORT=2525
--allowInjection	MB_ALLOW_INJECTION=true
--configfile	--configfile (CLI) or MB_CONFIGFILE
--datadir	--datadir (CLI) or MB_DATADIR
--loglevel debug	--loglevel debug or MB_LOGLEVEL=debug
--apikey	--apikey / --api-key (CLI) or MB_APIKEY; the key is read from x-api-key or Authorization
--localOnly	--local-only (CLI) or MB_LOCAL_ONLY=true
--rcfile	--rcfile (CLI) — a subset of keys, see the CLI Reference

Rift's flags are kebab-case. Mountebank's spellings --allowInjection, --noParse, --localOnly, --ipWhitelist, --logfile, --apikey and save --removeProxies are accepted as aliases (--logfile is --log, with no default file). A Mountebank client that sends the key in x-api-key needs no change; Rift also accepts it in Authorization, which wins when both are sent. --ip-whitelist, --origin, --mock, --formatter and --protofile are accepted but do nothing. An unrecognised --loglevel value is refused at startup instead of being ignored.

Step 4: Verify Functionality

Run your existing test suite against Rift:

# Your tests should work without modification
npm test
pytest
go test ./...

---

Feature Differences

Enhanced Performance

Rift provides significantly better performance:

• ~20–150x faster request processing on typical workloads (see Performance)
• Consistent latency regardless of stub count
• Lower memory usage due to Rust's efficiency

Additional Features

Rift includes features not in Mountebank:

1. Native Metrics: Built-in Prometheus metrics on /metrics
2. Rhai Scripting: Lightweight embedded scripting (in addition to JavaScript)
3. Flow State: Stateful testing with a per-process flow store

Minor Differences

Area	Mountebank	Rift
Logging	Custom format	Plain-text tracing lines; RUST_LOG takes a full filter
Metrics	Third-party	Built-in Prometheus
Admin UI	Built-in web UI	No web UI; a terminal UI (rift-tui) ships with the binaries
mb replay	Switches a running server's proxies to replay	rift replay --configfile <file> starts a server with that file loaded
Shutdown	—	SIGTERM/SIGINT shut down gracefully and exit 0, as Mountebank does; no --init needed in a container (#1155)
mutualAuth	Requests a client certificate (only with rejectUnauthorized) and never rejects one	Requires a client certificate; rejectUnauthorized/ca without mutualAuth, or rejectUnauthorized without ca, is refused with 400 — see Mutual TLS (#977)

Known HTTP Behavior Differences

Transfer-Encoding Header on 204 Responses

Rift follows HTTP specification more strictly than Mountebank in some cases:

Scenario	Mountebank	Rift
204 No Content with Transfer-Encoding	Includes header	Strips header

Why this happens: HTTP/1.1 specification (RFC 7230) states that responses with no message body (such as 204 No Content) should not include Transfer-Encoding or Content-Length headers. Rift's underlying HTTP library (hyper) enforces this correctly.

Impact: If your stubs define a 204 response with Transfer-Encoding: chunked, Rift will return the 204 status but without the Transfer-Encoding header. This is correct HTTP behavior and should not affect most applications.

Example:

{
  "responses": [{
    "is": {
      "statusCode": 204,
      "headers": {
        "Transfer-Encoding": "chunked"
      }
    }
  }]
}

• Mountebank: Returns 204 with Transfer-Encoding: chunked header
• Rift: Returns 204 without Transfer-Encoding header (per HTTP spec)

---

Configuration Examples

Mountebank CLI to Rift

# Mountebank
mb start \
  --port 2525 \
  --allowInjection \
  --loglevel warn \
  --configfile imposters.json

# Rift (equivalent)
docker run \
  -e MB_PORT=2525 \
  -e MB_ALLOW_INJECTION=true \
  -e MB_LOGLEVEL=warn \
  -v $(pwd)/imposters.json:/imposters.json \
  zainalpour/rift-proxy:latest \
  --configfile /imposters.json

# Rift binary (equivalent)
rift start --port 2525 --allowInjection --loglevel warn --configfile imposters.json

Docker Compose

services:
  rift:
    image: zainalpour/rift-proxy:latest
    ports:
      - "2525:2525"      # Admin API
      - "4545:4545"      # Imposter port
      - "9090:9090"      # Metrics (Rift addition)
    environment:
      - MB_PORT=2525
      - MB_ALLOW_INJECTION=true
      - MB_LOGLEVEL=info
    volumes:
      - ./imposters.json:/imposters.json
    command: ["--configfile", "/imposters.json"]

---

Troubleshooting

"Injection not allowed"

Enable injection via environment variable:

docker run -e MB_ALLOW_INJECTION=true zainalpour/rift-proxy:latest

Different Response Format

Rift may format JSON responses differently (but equivalently). If your tests compare exact string output, consider comparing parsed JSON instead.

TCP/SMTP Protocol Imposters

Rift imposters are HTTP/HTTPS only — a config whose protocol is tcp or smtp (or anything other than http/https) is rejected with an Invalid protocol error. For non-HTTP protocol mocking, continue using Mountebank.

Note this is separate from TCP fault injection: HTTP(S) imposters can simulate transport-level failures (connection reset, etc.) via _rift.fault.tcp or a top-level fault response — see Fault Injection.

---

Getting Help

• GitHub Issues - Report bugs or request features
• Documentation - Full documentation
• Performance Benchmarks - Compare with Mountebank