Getting Started with Rift

Rift is a high-performance, Mountebank-compatible HTTP/HTTPS mock server. This guide will help you install Rift and create your first imposter.

Installation

The easiest way to run Rift is using Docker:

# Pull the latest image (from GitHub Container Registry)
docker pull ghcr.io/etacassiopeia/rift-proxy:latest

# Or from Docker Hub
docker pull etacassiopeia/rift-proxy:latest

# Run Rift on port 2525 (Mountebank-compatible admin port)
docker run -p 2525:2525 ghcr.io/etacassiopeia/rift-proxy:latest

Download Binary

Download pre-built binaries from the releases page:

# Linux (x86_64)
curl -L https://github.com/EtaCassiopeia/rift/releases/latest/download/rift-http-proxy-linux-x86_64 -o rift
chmod +x rift
./rift

# macOS (Apple Silicon)
curl -L https://github.com/EtaCassiopeia/rift/releases/latest/download/rift-http-proxy-darwin-aarch64 -o rift
chmod +x rift
./rift

# macOS (Intel)
curl -L https://github.com/EtaCassiopeia/rift/releases/latest/download/rift-http-proxy-darwin-x86_64 -o rift
chmod +x rift
./rift

Build from Source

Requires Rust 1.70+:

git clone https://github.com/EtaCassiopeia/rift.git
cd rift
cargo build --release
./target/release/rift-http-proxy

Node.js / npm

For Node.js projects, install the official npm package:

npm install @rift-vs/rift

Usage:

import rift from '@rift-vs/rift';

const server = await rift.create({ port: 2525 });
// Create imposters, run tests...
await server.close();

See the Node.js Integration Guide for complete documentation.

Verify Installation

Once Rift is running, verify it’s working:

# Check the admin API
curl http://localhost:2525/

# Expected response:
{
  "_links": {
    "imposters": { "href": "/imposters" },
    "config": { "href": "/config" },
    "logs": { "href": "/logs" }
  }
}

Your First Imposter

Create a simple HTTP mock that responds to GET requests:

curl -X POST http://localhost:2525/imposters \
  -H "Content-Type: application/json" \
  -d '{
    "port": 4545,
    "protocol": "http",
    "name": "My First Imposter",
    "stubs": [{
      "predicates": [{
        "equals": {
          "method": "GET",
          "path": "/api/greeting"
        }
      }],
      "responses": [{
        "is": {
          "statusCode": 200,
          "headers": { "Content-Type": "application/json" },
          "body": { "message": "Hello from Rift!" }
        }
      }]
    }]
  }'

Test your imposter:

curl http://localhost:4545/api/greeting

# Response:
{"message":"Hello from Rift!"}

Load Existing Configuration

If you have an existing Mountebank configuration file, load it directly:

# Using Docker
docker run -p 2525:2525 -v $(pwd)/imposters.json:/imposters.json \
  ghcr.io/etacassiopeia/rift-proxy:latest --configfile /imposters.json

# Using binary
./rift --configfile imposters.json

Example imposters.json:

{
  "imposters": [
    {
      "port": 4545,
      "protocol": "http",
      "stubs": [
        {
          "predicates": [{ "equals": { "path": "/users" } }],
          "responses": [{ "is": { "statusCode": 200, "body": "[]" } }]
        }
      ]
    }
  ]
}

Next Steps

Table of contents