docker run -p 4000:4000 -v $(pwd)/db:/db -d hhaluk/mocktail:3.1.6

docker-compose up -d

docker-compose up -d --build

• Create Mock APIs - Support for GET/POST/PUT/PATCH/DELETE methods
• Custom Status Codes - Return any HTTP status (200, 404, 500, etc.) to test error handling
• Response Delays - Add 0-30000ms delay to simulate network latency and loading states
• JSON Editor - CodeMirror-powered editor with syntax highlighting, error detection, and code folding
• Code Examples - Instantly generate cURL, Node.js, Python, and Go code snippets for any endpoint
• Randomize & Anonymize ⚠️ Beta - Generate realistic fake data with 20+ faker types plus Custom (fixed value) and AI Generate (prompt-based) modes, with per-field configuration, live preview, and "apply same value to all" support
• Irregular Array Support - Handles arrays with inconsistent object structures, showing field frequency and applying configs selectively
• Modern Dashboard - Clean, intuitive interface built with React and Chakra UI v3
• Catalog View - Browse, search, and manage all your mock endpoints with quick actions and persistent selection
• Quick Edit - Update status codes and delays instantly via gear icon in catalog
• Test Endpoints - Test mocks directly from the catalog list with visual feedback
• Import/Export - Export mocks to JSON and import them anywhere
• Persistent Storage - SQLite database with volume mounting
• Multi-Platform - Native support for amd64 and arm64 (Intel, Apple Silicon, Raspberry Pi)
• Health Check - /health endpoint for monitoring and orchestration
• Customizable URLs - Override display URLs for reverse proxy/custom domain setups

Mocktail includes an MCP (Model Context Protocol) server that lets AI assistants like Claude manage your mock endpoints through natural language. Available on npm as mocktail-mcp.

Examples: "List all my mocks", "Create a GET /api/users mock returning a list of users", "Import mock endpoints for a blog API."

claude mcp add mocktail \
  -e MOCKTAIL_URL=http://localhost:4000 \
  -e MOCKTAIL_API_KEY=your-api-key \
  -- npx mocktail-mcp

{
  "mcpServers": {
    "mocktail": {
      "command": "npx",
      "args": ["mocktail-mcp"],
      "env": {
        "MOCKTAIL_URL": "http://localhost:4000",
        "MOCKTAIL_API_KEY": "your-api-key"
      }
    }
  }
}

claude mcp add mocktail \
  -e MOCKTAIL_URL=http://localhost:4000 \
  -e MOCKTAIL_API_KEY=your-api-key \
  -- node /path/to/mocktail/mcp-server/index.js

{
  "mcpServers": {
    "mocktail": {
      "command": "node",
      "args": ["/path/to/mocktail/mcp-server/index.js"],
      "env": {
        "MOCKTAIL_URL": "http://localhost:4000",
        "MOCKTAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables:

Note: If you configured MOCKTAIL_BASE_URL for a custom domain or reverse proxy, use that same URL for MOCKTAIL_URL (e.g. https://api.mycompany.com/mocktail becomes MOCKTAIL_URL=https://api.mycompany.com).

See mcp-server/README.md for more details.

MOCKTAIL_BASE_URL (optional)

Override the Mocktail URL displayed in the dashboard. Useful when deploying behind a reverse proxy or custom domain.

Note: The legacy REACT_APP_MOCKTAIL_URL environment variable is still supported for backwards compatibility.

# Example: Custom domain
MOCKTAIL_BASE_URL=https://api.mycompany.com/mocktail

# Example: Reverse proxy
MOCKTAIL_BASE_URL=https://gateway.example.com/mocktail

If not set, defaults to:

• Development: http://localhost:4000/mocktail
• Production: [your-domain]/mocktail

CORS Configuration (optional)

Configure Cross-Origin Resource Sharing (CORS) policies for the mock API.

# Allowed origins (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000

# Allowed HTTP methods (comma-separated)
# Default: GET,POST,PUT,PATCH,DELETE,OPTIONS
MOCKTAIL_CORS_METHODS=GET,POST,PUT,DELETE

# Allowed headers (comma-separated)
# Default: * (allow all)
MOCKTAIL_CORS_HEADERS=Content-Type,Authorization,X-API-Key

# Allow credentials (cookies, auth headers)
# Default: false
MOCKTAIL_CORS_CREDENTIALS=true

Docker Example:

docker run -p 4000:4000 \
  -e MOCKTAIL_CORS_ORIGINS=https://myapp.com \
  -e MOCKTAIL_CORS_CREDENTIALS=true \
  hhaluk/mocktail:latest

Docker Compose Example:

services:
  mocktail:
    image: hhaluk/mocktail:latest
    ports:
      - "4000:4000"
    environment:
      MOCKTAIL_CORS_ORIGINS: "https://myapp.com,http://localhost:3000"
      MOCKTAIL_CORS_CREDENTIALS: "true"
    volumes:
      - ./db:/db

⚠️ Important Security Rule:

DO NOT combine wildcard origins with credentials:

# ❌ INVALID - Browsers will reject this combination
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=true

# ✅ VALID - Use specific origins with credentials
MOCKTAIL_CORS_ORIGINS=https://myapp.com,http://localhost:3000
MOCKTAIL_CORS_CREDENTIALS=true

# ✅ VALID - Use wildcard without credentials (default)
MOCKTAIL_CORS_ORIGINS=*
MOCKTAIL_CORS_CREDENTIALS=false

When MOCKTAIL_CORS_CREDENTIALS=true, you must specify exact origins (no * wildcard).

MOCKTAIL_API_KEY (optional)

Protect mock endpoints with API key authentication. When set, all requests to /mocktail/* must include the API key.

# Set API key
MOCKTAIL_API_KEY=your-secret-key-here

Usage:

Clients must provide the key via header or query parameter:

# Via header (recommended)
curl http://localhost:4000/mocktail/users \
  -H "X-API-Key: your-secret-key-here"

# Via query parameter
curl http://localhost:4000/mocktail/users?api_key=your-secret-key-here

What's Protected:

• 🔒 Mock endpoints (/mocktail/*) - Requires API key
• ✅ Dashboard (/) - No auth needed
• ✅ Core API (/core/v1/*) - No auth needed (dashboard uses this)
• ✅ Health check (/health) - No auth needed

Security Note: If not set, mock endpoints are open (no authentication). This is fine for local development or private networks.

See the full Changelog for all release notes.

v3.1.6 — Backend & MCP endpoint leading-slash normalization (fixes /mocktail//posts/1-style double-slash URLs)

v3.1.5 — MCP endpoint path normalization (fixes double slashes), catalog pagination

v3.1.4 — MCP Server AI integration (npx mocktail-mcp), Randomize & Anonymize UX overhaul (three-column layout, Custom & AI Generate types)

v3.1.3 — Backend Logs tab with real-time monitoring, enhanced code examples with API key support, critical Go string mutation bugfix

v3.1.2 — API key authentication, configurable CORS, .env file support

v3.1.1 — Cross-reference detection, review modal, Randomize & Anonymize improvements

• Custom Status Codes & Delays - Configure HTTP status codes and response delays per endpoint
• CodeMirror JSON Editor - Professional code editor with syntax highlighting and error detection
• Quick Actions - Test, edit, copy, and delete directly from the catalog list with icon buttons
• Chakra UI v3 - Complete UI library upgrade with modern components
• Go 1.24 & GORM v2 - Latest backend stack with improved performance
• Fiber v2.52 - Updated web framework with security patches
• Cleaner Architecture - Improved code organization and consistency
• Health Endpoint - /health for Docker health checks and monitoring
• Auto-Setup - Database directory auto-creates on first run
• Import/Export UI - Moved to Catalog tab with better UX

• Import Tab Removed - Import functionality now in Catalog tab
• Drag & Drop Removed - Simplified to native file input
• react-dropzone Removed - Reduced dependencies

v3.0 is not backwards compatible with v2.x databases.

However, you can migrate your data:

1. In v2, export your mocks to JSON (Catalog → Export)
2. Install v3.0
3. Import the JSON file (Catalog → Import)

Your mock endpoints will work unchanged - only the internal database structure changed.

# Run backend dev server
make dev-api

# Run dashboard dev server (in another terminal)
make dev-dashboard

# Build everything
make build

# Build Docker image
make build-docker

cd mocktail-api
go run main.go

cd mocktail-dashboard
yarn install
yarn start

• Changelog