LiveMock

📚document

English | 简体中文

LiveMock is a comprehensive tool for API development and testing, offering mock data, request proxying, and logging, to streamline workflows and track traffic.

🎆 Preview

📦 features

• Dynamic mocking - Apply mock changes without restarting the server
• Web dashboard - The dashboard is served by the same server and runs in any modern browser
• api proxy support Forward requests to actual API when needed
• support mockjs - Generate mock data with mockjs library
• Logging and analytics - Log requests/responses for analysis.

🚧 Installation

Install from npm

The backend and dashboard are published to npm as the package livemock. No clone or build step is needed — run it straight from the registry:

npx livemock

Or install it globally so the livemock command stays on your PATH:

npm install -g livemock
livemock

Either way the server starts at http://localhost:9002 (the dashboard is at /dashboard) using a db directory created in the working directory. To keep the data somewhere else, start it from the directory you want to use, or point LIVEMOCK_DB_PATH at an absolute path:

LIVEMOCK_DB_PATH=/var/lib/livemock npx livemock

Note

Requires Node.js 18 or newer. Next time you run npx livemock, npm reuses the cached copy; add @latest (that is, npx livemock@latest) to pick up a newer release.

Install from source instead (for contributing / development)

1.This project uses Yarn Workspaces, so you need to enable corepack.

corepack enable

2.clone the project

git clone https://github.com/alinGmail/LiveMock.git

3.install dependencies

cd LiveMock 
yarn install

[!NOTE] If you are in China, you can set the ELECTRON_MIRROR environment variables to https://npmmirror.com/mirrors/electron/

4.build the forntEnd code

yarn run web-build

5.run the project

yarn run web-start

the server will be running at http://localhost:9002 by default

configuration

environment variable	default	description
LIVEMOCK_PORT	9002	port the web server listens on
LIVEMOCK_DB_PATH	db	directory where the database files are stored
LIVEMOCK_COOKIE_SECURE	false	set to true when the dashboard is served over HTTPS so the session cookie is only sent over TLS (HTTPS itself is terminated by your reverse proxy)
LIVEMOCK_TRUST_PROXY	(unset)	comma-separated list of reverse-proxy IPs/CIDRs whose X-Forwarded-For header is trusted (for example 127.0.0.1,10.0.0.0/8). Unset or false ignores forwarding headers entirely. A "trust everyone" mode is intentionally not supported; an invalid entry stops the server at startup

For example, to run on another port:

LIVEMOCK_PORT=8100 npx livemock

(When working from a source checkout, use LIVEMOCK_PORT=8100 yarn run web-start instead.)

The control-plane API is served under /api (for example http://localhost:9002/api/project/) and the Socket.IO endpoint is /api/socket.io. In development (yarn web-dev), the front-end calls relative URLs and the Vite dev server proxies /api (websocket upgrade included) to the backend, so no server URL needs to be configured. In production the backend serves the UI at /dashboard on the same origin.

With Docker Compose the same variable controls both the listener and the published port:

LIVEMOCK_PORT=8100 docker compose up

Authentication

LiveMock is protected by a single account.

• First run: the first visit shows an initialization form. Create the account (username + password) and you are signed in. After that, the registration endpoint is permanently closed and every visit requires signing in.
• Sessions: the login is kept in an httpOnly cookie for 7 days of activity and survives backend restarts. Logging out ends only the current session, so several devices can stay signed in at the same time.
• Protection: the dashboard, every /api endpoint and the Socket.IO connection require a login. The mock listener ports (for example http://localhost:8088) stay public so mocked APIs and test clients keep working.
• Brute force: repeated failed logins from one IP back off exponentially, capped at 30 minutes. The account itself is never locked.
• Password changes are available on the Config page and end all other sessions.
• Public deployments: register immediately after starting the server — the first caller to register owns the account. There is no setup token by design. Behind a reverse proxy, set LIVEMOCK_TRUST_PROXY so the login throttle sees the real client IP, and LIVEMOCK_COOKIE_SECURE=true when serving over HTTPS.

If you lose the credentials, stop the backend and run:

npx livemock reset-admin <new-username>

Use livemock reset-admin <new-username> for a global install, or yarn workspace livemock reset-admin <new-username> from a source checkout. You are prompted for the new password twice (hidden). The command resets the username and password and invalidates all sessions; start the backend again and log in. The backend must be stopped first because the database is written from memory while the server runs.

With Docker Compose the optional settings can be passed through the environment:

LIVEMOCK_COOKIE_SECURE=true LIVEMOCK_TRUST_PROXY=127.0.0.1 docker compose up

MCP server

LiveMock ships a separate MCP server, livemock-mcp, so AI clients such as Claude Code, Claude Desktop and Cursor can manage projects, expectations, groups and request logs from the editor.

1. Open Settings → API tokens and create a named token. Copy it once; LiveMock stores only a hash.
2. Point the MCP server at the running web instance:

LIVEMOCK_URL=http://localhost:9002 \
LIVEMOCK_API_TOKEN=lmk_replace_me \
npx -y livemock-mcp

Or let add-mcp write the user-level client configuration:

npx add-mcp@2 livemock-mcp -g -a claude-code \
  --env 'LIVEMOCK_URL=http://localhost:9002' \
  --env 'LIVEMOCK_API_TOKEN=${LIVEMOCK_API_TOKEN}'

add-mcp prompts for the token, infers the server name livemock, and supports Cursor, OpenCode, Claude Desktop and other clients via -a. Keep -g so the token is not written into a project file, and see mcp/README.md for the full install notes.

Tokens have full access to the data plane but cannot create or revoke other tokens or change the account password. Changing the password or running livemock reset-admin revokes every token. See mcp/README.md for client configurations, the tool list and raw expectation examples.

📌Quick Start

After installing liveMock, the first visit asks you to create the account for the instance. After that, sign in and you will be able to access the welcome page (a page to create a project). Simply input the project name and submit the form, and you will be redirected to the dashboard page.

Creating an Expectation

An expectation consists of several matchers and an action. When a request matches all its matchers, the defined action will be taken, such as responding with a JSON.

To create an expectation, click the "Add Expectation" button. After that, you will see the newly created expectation in the list.

Creating a Matcher

To create a matcher, click the "Add Matcher" button. Change the matcher to "path start_with /" to match all requests.

Creating an Action

An action defines what the expectation will do. Three actions are supported: custom response, proxy and static directory.

To create an action, click the "Create Action" button. By default, the action type is set to custom response, but you can change it to proxy. Once the action is created, click on it and input the desired JSON string in the content field. It will be automatically saved.

Starting the Project

On the top, you will find a green start button. Clicking it will start the project. Furthermore, ensure that your expectation is activated. You can then visit http://localhost:8088 to see the JSON response.

🧱document

What is expectation

An expectation consists of several matchers and an action. When a request matches all its matchers, the defined action will be taken, such as responding with a JSON.

How to create expectation

To create an expectation, goto the expectation list page and click the "Add Expectation" button. After that, you will see the newly created expectation in the list.

property of an expectation

• delay: the delay time of the response,unit is ms.
• priority: the expectation has highter priority will matcher first.
• activate: if the expectation is inactivate, it will be skip when the request match.
• matchers: the matchers of the expectation, if the request match all matchers, the action of the expectation will take.
• action: the action of the expectation,current support two action. custom response and proxy.

matchers

The matcher consists of three parts: type, comparator, and value. These three parts determine whether a request can be matched. Now livemock supports five types, which are:

• method: the method of the request, such as GET, POST, PUT, etc.
• path: the path of the request, the path is start with /,like /student/123
• header: the headers of the request
• query: the parameters in the request URL
• param: the parameters in the request body

Here are some examples of matchers:

• path START_WITH /book/: matches all request paths that start with /book/.
• query teacher_name CONTAINS tom: matches all requests that have a teacher_name query parameter, and the value of the teacher_name query parameter contains "tom".
• param teacher_name IS tom: matches all requests that have a body, and the body has a teacher_name parameter,value is tom. For example, a request with a JSON body like the one below:

{
  "teacher_name": "tom"
}

action

there are three types of action:

• custom response: response some custom text or JSON to the request, you can also set the headers of the response
• proxy: make the request forward to another host.
• static: serve files from a folder on the machine running LiveMock.

You can customize the header of the response, both in custom response and proxy actions.

request log

Livemock will record all requests that match an expectation as a JSON object and display them on the request log page. Below is an example of a recorded object:

{
    "id": 100099, 
    "expectationId": "c26a2cef-8ac7-4ce4-8a4b-595c850488be", 
    "proxyInfo": {
      "isProxy": false,
      "proxyHost": null,
      "proxyPath": null
    }, 
    "req": {
        "body": { }, 
        "headers": {
            "host": "localhost:8088", 
            "connection": "keep-alive", 
            "cache-control": "max-age=0", 
            "upgrade-insecure-requests": "1", 
            "user-agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/115.0.0.0 Safari/537.36", 
            "accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,/;q=0.8,application/signed-exchange;v=b3;q=0.7", 
            "accept-encoding": "gzip, deflate, br"
        }, 
        "method": "GET", 
        "path": "/olkioi", 
        "requestDate": "2023-08-04T13:14:51.042Z"
    }, 
    "res": {
        "body": {
            "name": "John", 
            "age": 30, 
            "hobbies": [
                "reading", 
                "hiking", 
                "coding"
            ]
        }, 
        "duration": 0, 
        "headers": {
            "x-powered-by": "Express", 
            "content-type": "text/plain"
        }, 
        "rawBody": "{\"name\":\"John\",\"age\":30,\"hobbies\":[\"reading\",\"hiking\",\"coding\"]}", 
        "responseDate": "2023-08-04T13:14:51.042Z", 
        "status": 200, 
        "statusMessage": "OK"
    }, 
    "meta": {
        "revision": 1, 
        "created": 1691154891042, 
        "version": 0, 
        "updated": 1691154891042
    }, 
    "$loki": 95
}

On the request log page, there are predefined columns such as "Method," "Status," "Body," and "Root." You can also add custom columns with three customizable properties: name, path, and display type.

• Name: The name of the column, which is displayed in the table header.
• Path: Defines the value of the path of the request JSON object to show. For example, "req.method" uses the value of JSONObject.req.method to display in the table body.
• Display type: Defines how to display the value. You can display it as text or a JSON tree.