Mockarty Quick Start Guide

Get up and running with Mockarty in 10 minutes. This guide walks you through installation, creating your first mock, testing it, and exploring the key features.

Table of Contents

1. What is Mockarty
2. Installation
3. First Launch
4. Understanding Namespaces
5. Create Your First Mock
6. Test Your Mock
7. Use Faker for Dynamic Responses
8. Add Conditions
9. Import from OpenAPI
10. API Testing
11. Fuzzing
12. Generate Standalone Server
13. Next Steps

What is Mockarty

Mockarty is a powerful, multi-protocol mock server designed for modern development and QA workflows. It enables you to simulate any backend service without writing code.

Supported protocols:

Direct protocols — served by the Mockarty node at /stubs/{namespace}/...:

• HTTP / REST — Full REST API mocking with route parameters, headers, query params, and body conditions
• GraphQL — Query and mutation detection with flexible response mocking
• SOAP — WSDL-based service mocking
• SSE — Server-Sent Events for real-time data streams
• MCP — Model Context Protocol tools, resources, and prompts

Generated server protocols — mocks are created in the UI, but traffic is served by a standalone server built with mockarty-server-generator (see Server Generator Guide):

• gRPC — Unary and streaming mock responses from .proto files
• WebSocket — Bidirectional communication mocking
• Kafka — Topic-based message mocking with consumer/producer simulation
• RabbitMQ — Queue and exchange mocking with message routing
• TCP / UDP — Raw socket communication mocking

Key features:

• Web UI with visual Mock Constructor — no code required
• AI Assistant — describe what you need in natural language and let the agent create mocks for you
• Faker engine — generate realistic dynamic data (names, emails, UUIDs, addresses, dates, and more)
• JsonPath interpolation — extract values from requests and use them in responses
• Store system — maintain state across requests with Global, Chain, and Mock stores
• Condition matching — route requests to different responses based on body, headers, query params
• Proxy mode — forward requests to real services while adding delay, modifying headers, or logging
• OpenAPI / Swagger import — generate mocks from your existing API specs
• API Tester — built-in Postman-like tool for testing your mocks and real APIs
• Fuzz testing — built-in fuzzer to discover vulnerabilities in your APIs
• Code generators — generate standalone gRPC, MCP, Kafka, RabbitMQ, and other servers
• Multi-node architecture — scale with resolver nodes and runner agents

Installation

Option A: Download the Binary

Visit the Downloads page and download the binary for your platform:

• macOS (Apple Silicon): mockarty-darwin-arm64
• macOS (Intel): mockarty-darwin-amd64
• Linux (x86_64): mockarty-linux-amd64
• Linux (ARM64): mockarty-linux-arm64
• Windows (x86_64): mockarty-windows-amd64.exe

Make the binary executable and run it (macOS/Linux):

chmod +x mockarty-darwin-arm64
DB_USE=sqlite ./mockarty-darwin-arm64

Option B: Docker Image from Binary

Mockarty does not have a public Docker Hub image. You build your own image from the downloaded binary. Create a Dockerfile:

FROM alpine:3.20
RUN apk add --no-cache ca-certificates tzdata
COPY mockarty /usr/local/bin/mockarty
RUN chmod +x /usr/local/bin/mockarty
EXPOSE 5770
ENTRYPOINT ["mockarty"]

Build and run:

docker build -t mockarty:latest .
docker run -d --name mockarty -p 5770:5770 -e DB_USE=sqlite mockarty:latest

Option C: Docker Compose with PostgreSQL

For production-like setups with PostgreSQL:

# docker-compose.yml
services:
  mockarty:
    build: .
    ports:
      - "5770:5770"
    environment:
      DB_USE: pg
      DB_DSN: "postgres://mockarty:mockarty@postgres:5432/mockarty?sslmode=disable"
    depends_on:
      - postgres

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: mockarty
      POSTGRES_PASSWORD: mockarty
      POSTGRES_DB: mockarty
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

docker compose up -d

First Launch

The simplest way to start is with the built-in SQLite database — no external dependencies required.

Start with SQLite

DB_USE=sqlite ./mockarty-darwin-arm64

Mockarty will:

1. Create a SQLite database at ~/.mockarty/data.db
2. Run all migrations automatically
3. Create a default admin user (login: admin, password: admin)
4. Create a default namespace called sandbox
5. Start the HTTP server on port 5770

You should see output similar to:

INFO  Starting Mockarty ...
INFO  Using SQLite database: ~/.mockarty/data.db
INFO  Migrations applied successfully
INFO  HTTP server listening on :5770

Open the Web UI

Open your browser and navigate to:

http://localhost:5770/ui/

You will see the Mockarty login page. Log in with the default credentials: admin / admin.

After logging in, you will see the main dashboard with the sidebar navigation.

Security note: Change the default admin password after your first login. Go to Settings in the sidebar to update your credentials.

Understanding Namespaces

Mockarty organizes all resources into namespaces. A namespace is an isolated workspace — each namespace has its own mocks, stores, and test collections. This is a core concept you need to understand before creating mocks.

What is a Namespace?

Think of a namespace as a project folder. If you have multiple teams or microservices, each can have its own namespace with independent mocks that do not interfere with each other.

On first launch, Mockarty automatically creates a namespace called sandbox — a shared sandbox environment available to all users. Administrators and Support users (system roles) can create new namespaces. The Owner of a namespace (namespace role) can add users to their namespace.

The URL Pattern

All mock requests are routed through namespaces. The URL pattern is:

http://localhost:5770/stubs/{namespace}/{your-route}

For example, if you create a mock with route /api/users in the sandbox namespace, you call it at:

http://localhost:5770/stubs/sandbox/api/users

If you later create a namespace called payments and add a mock with route /api/invoices, you would call it at:

http://localhost:5770/stubs/payments/api/invoices

Managing Namespaces

You can create and manage namespaces in the Admin section of the sidebar. Each namespace can have:

• Its own set of mocks
• Assigned users with specific roles
• Independent Global and Chain stores
• Separate test collections and environments

For this Quick Start guide, we will use the sandbox namespace that is created automatically.

Create Your First Mock

Let’s create a simple HTTP mock that returns a list of users.

Step 1: Open the Constructor

Click Constructor in the sidebar menu. This is the visual mock builder.

Step 2: Configure the Route

Fill in the basic mock settings:

Step 3: Define the Response

In the Response section, set:

• Status Code: 200
• Content-Type: application/json
• Response Body:

{
  "users": [
    {
      "id": "$.fake.UUID",
      "name": "$.fake.Name",
      "email": "$.fake.Email",
      "age": "$.fake.IntBetween(18, 65)"
    },
    {
      "id": "$.fake.UUID",
      "name": "$.fake.Name",
      "email": "$.fake.Email",
      "age": "$.fake.IntBetween(18, 65)"
    }
  ],
  "total": 2
}

Step 4: Save the Mock

Click the Create Mock button. You will see a success notification and the mock will appear in the Mocks list.

Test Your Mock

Now let’s call the mock and see the response. Remember, all mock calls go through the namespace URL pattern.

Using curl

curl -s http://localhost:5770/stubs/sandbox/api/users | jq

Example response:

{
  "users": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "John Smith",
      "email": "john.smith@example.com",
      "age": 34
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba0987654321",
      "name": "Emily Johnson",
      "email": "emily.johnson@example.net",
      "age": 28
    }
  ],
  "total": 2
}

Every call generates new random data thanks to Faker functions. Call it again and you will get different names, emails, and UUIDs.

Using the Built-in API Tester

You can also test directly from the Mockarty UI:

1. Go to API Tester in the sidebar
2. Create a new request
3. Set method to GET and URL to http://localhost:5770/stubs/sandbox/api/users
4. Click Send

Use Faker for Dynamic Responses

Faker functions generate realistic random data on every request. Use them in your response payloads with the $.fake. prefix.

Common Faker Functions

Request Data Interpolation

You can also reference values from the incoming request:

Example: Echo User Data Back

Create a mock for POST /api/users that echoes submitted data with generated fields:

{
  "id": "$.fake.UUID",
  "name": "$.req.name",
  "email": "$.req.email",
  "createdAt": "$.fake.DateTime",
  "status": "active"
}

When you POST {"name": "Alice", "email": "alice@example.com"}, the response will include the submitted name and email along with a generated UUID and timestamp.

Test it:

curl -s -X POST http://localhost:5770/stubs/sandbox/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}' | jq

Add Conditions

Conditions let you return different responses based on the incoming request. This is how you simulate realistic API behavior.

Example: Different Responses by User ID

Create a mock for GET /api/users/:id with two response variants.

Response 1: Known User (condition: id equals “1”)

Condition:

• Type: pathParam
• Key: id
• Assert: equals
• Value: 1

Response (Status 200):

{
  "id": 1,
  "name": "Admin User",
  "role": "admin"
}

Response 2: User Not Found (default, lower priority)

Response (Status 404):

{
  "error": "User not found",
  "requestedId": "$.pathParam.id"
}

Test the conditional mock:

# Returns the admin user (condition matches)
curl -s http://localhost:5770/stubs/sandbox/api/users/1 | jq

# Returns 404 (no condition matches, falls through to default)
curl -s http://localhost:5770/stubs/sandbox/api/users/999 | jq

Condition Types

Assert Actions

Setting Up Conditions in the UI

1. In the Constructor, scroll to the Conditions section
2. Click Add Condition
3. Select the condition type (body, header, queryParam, pathParam)
4. Enter the key and expected value
5. Choose the assert action

Multiple conditions on a single mock use AND logic — all conditions must match for the response to be selected.

Import from OpenAPI

If you already have an OpenAPI (Swagger) specification, Mockarty can generate mocks for all your endpoints automatically.

Step 1: Open the Generator

Click Generator in the sidebar menu.

Step 2: Upload Your Spec

You can either:

• Paste a URL to your OpenAPI spec (JSON or YAML)
• Upload a file from your computer
• Paste the content directly into the editor

Supported formats:

• OpenAPI 3.0 / 3.1 (JSON and YAML)
• Swagger 2.0 (JSON and YAML)

Step 3: Configure Generation Options

Choose your generation preferences:

Step 4: Generate

Click Generate Mocks. Mockarty will create a mock for every endpoint in your spec.

Step 5: Review and Test

Go to the Mocks page to see all generated mocks. Each mock will have:

• The correct route and HTTP method
• Response payload based on schema definitions
• Appropriate status codes
• Faker-enhanced dynamic values (if enabled)

You can edit any generated mock in the Constructor to customize it further. Remember to test them using the namespace URL pattern:

curl -s http://localhost:5770/stubs/sandbox/your-generated-route | jq

API Testing

Mockarty includes a built-in API testing tool similar to Postman. Use it to test your mocks, real APIs, or a combination of both.

Create a Collection

1. Go to API Tester in the sidebar
2. Click New Collection
3. Name it (e.g., “User API Tests”)

Add a Request

1. Click Add Request inside your collection
2. Configure:
   • Name: Get Users
   • Method: GET
   • URL: http://localhost:5770/stubs/sandbox/api/users
3. Click Save

Add Headers and Body

For POST/PUT requests, you can add:

• Headers — key-value pairs (e.g., Content-Type: application/json)
• Body — raw JSON, form data, or other formats
• Query Parameters — added to the URL automatically

Add Test Scripts

Write JavaScript test scripts to validate responses:

// Check status code
pm.test("Status is 200", function() {
    pm.response.to.have.status(200);
});

// Check response body
pm.test("Has users array", function() {
    var jsonData = pm.response.json();
    pm.expect(jsonData.users).to.be.an('array');
    pm.expect(jsonData.users.length).to.be.greaterThan(0);
});

// Check individual fields
pm.test("User has required fields", function() {
    var user = pm.response.json().users[0];
    pm.expect(user).to.have.property('id');
    pm.expect(user).to.have.property('name');
    pm.expect(user).to.have.property('email');
});

Run Tests

Click Send to execute a single request, or Run Collection to execute all requests in sequence.

Results show:

• Status code and response time
• Response body with syntax highlighting
• Test pass/fail status
• Response headers

Fuzzing

Mockarty includes a built-in fuzz testing engine that helps you discover vulnerabilities and unexpected behavior in your APIs. Fuzzing sends a wide range of malformed, unexpected, and malicious inputs to your endpoints to see how they respond.

Access the Fuzzer

Click Fuzzing in the sidebar menu to open the fuzzing interface.

Quick Fuzz

The fastest way to start is with a quick fuzz test:

1. Enter the Target URL — this can be any HTTP endpoint (your mocks, staging APIs, or local services)
2. Select Payload Categories to test against:
   • SQL Injection — common SQL injection patterns
   • XSS — cross-site scripting payloads
   • Path Traversal — directory traversal attempts
   • Command Injection — OS command injection patterns
   • Header Injection — HTTP header manipulation
   • Overflow — buffer overflow and large input tests
3. Configure the request method and any required headers (e.g., authentication tokens)
4. Click Start Fuzzing

Understanding Results

As the fuzzer runs, results appear in real time. Each finding includes:

• Severity level — Critical, High, Medium, Low, or Info
• Payload — the exact input that triggered the finding
• Response details — status code, response body, and timing
• Category — which payload category the finding belongs to

Example: Fuzz a Login Endpoint

To quickly test a login endpoint for SQL injection:

1. Set Target URL to http://localhost:5770/stubs/sandbox/api/login
2. Set Method to POST
3. Set Body template: {"username": "{{payload}}", "password": "test"}
4. Select SQL Injection category
5. Click Start Fuzzing

The fuzzer will replace {{payload}} with various SQL injection strings and report any suspicious responses (unexpected status codes, error messages leaking internal details, etc.).

When to Use Fuzzing

• Before deployment — test your real APIs for common vulnerabilities
• Mock validation — ensure your mocks handle edge cases gracefully
• CI/CD integration — run fuzz tests as part of your quality pipeline
• Security audits — systematic testing of input validation

Generate Standalone Server

Some protocols (gRPC, Kafka, RabbitMQ, WebSocket, TCP, UDP) require a generated standalone server to serve traffic. You create the mocks in the Mockarty UI, then generate a server that receives protocol-specific requests and calls back to the Mockarty node for mock resolution.

The server generator also works with direct protocols (OpenAPI, GraphQL, SOAP, SSE, MCP) — useful for creating self-contained mock servers for CI/CD.

Note: The server generator requires a valid license with the api-first-generator feature enabled on the Mockarty node when using the -create-mocks mode.

Install the Server Generator

Download mockarty-server-generator from the Downloads page:

• macOS (Apple Silicon): mockarty-server-generator-darwin-arm64
• macOS (Intel): mockarty-server-generator-darwin-amd64
• Linux (x86_64): mockarty-server-generator-linux-amd64

chmod +x mockarty-server-generator-darwin-arm64

Example: Generate from OpenAPI Spec

./mockarty-server-generator openapi \
  -input ./petstore.yaml \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox

This creates a complete Go project with:

• All routes from the OpenAPI spec
• Mock responses based on schema definitions
• A built-in admin UI at /ui
• Health endpoint at /health
• Vendored dependencies (no internet required to build)

Example: Generate gRPC Server

gRPC mocks are created in the Mockarty UI (Constructor → gRPC protocol), but to actually serve gRPC traffic, you need a generated server:

# Generate server + create mocks from proto files
./mockarty-server-generator grpc \
  -input ./proto/ \
  -output server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -namespace sandbox \
  -server-name my-grpc-service

Proto files must include option go_package = "/your_company/service_name"; (starting with /).

Example: Generate Kafka Server

./mockarty-server-generator kafka \
  -input kafka-config.json \
  -output kafka_server.go \
  -package main \
  -create-mocks \
  -api-token mk_your_token \
  -server-name my-kafka-server

Where kafka-config.json defines topics, broker address, and consumer group. See the Server Generator Guide for the full configuration format.

Build and Run the Generated Server

All generated servers include vendored dependencies and can be built completely offline:

cd generated-server
go build -mod=vendor -o server .

# Run with required env vars
HTTP_PORT=8080 \
HTTP_ADMIN_BASE_URL=http://localhost:5770 \
NAMESPACE=sandbox \
./server

The generated server connects to the Mockarty node (HTTP_ADMIN_BASE_URL) for mock resolution on every request. The Mockarty node must be running and accessible.

Supported Server Types

Usage: mockarty-server-generator <type> [flags]

Next Steps

You now have a working Mockarty instance with your first mock. Here is where to go next:

Learn More

Common Next Steps

1. Set up PostgreSQL for production use — SQLite is great for development, but PostgreSQL is recommended for teams and production environments.

2. Create additional namespaces to organize mocks by project or team. Go to the Admin panel to create namespaces and assign users.

3. Import existing APIs using the OpenAPI Generator or HAR file import. Record real API traffic and create mocks automatically.

4. Use the AI Assistant — go to Agent Chat in the sidebar and describe what mocks you need in natural language. The AI will create them for you.

5. Set up CI/CD integration — use the REST API to create and manage mocks programmatically in your test pipelines.

6. Explore proxy mode — forward requests to real services while adding delays, modifying responses, or logging traffic.

7. Scale with resolver nodes — deploy multiple resolver nodes for high-availability mock serving. See the Integrations Guide for details.

8. Run fuzz tests — use the built-in fuzzer to test your real APIs for vulnerabilities before deployment.

Getting Help

• Documentation: All guides are available in the sidebar under the Docs section
• Health Check: Visit http://localhost:5770/health to verify the server is running
• Swagger UI: Visit http://localhost:5770/swagger/ for interactive API documentation
• Logs: Check the console output for structured logs with request details

Happy mocking!

See Also

• Faker Reference — Complete list of all Faker functions
• JsonPath Guide — Advanced request data extraction and response interpolation
• Store Systems — Global, Chain, and Mock stores for stateful mocking
• Installation & Deployment — Production Docker deployment with PostgreSQL
• UI User Guide — Comprehensive guide to the Web UI