Mockarty CLI Container — universal multi-mode image

The mockarty/cli container image is a single, universal artefact that powers every test-time workflow Mockarty supports — mocking, load testing, functional testing, fuzzing, and chaos engineering. One image, one binary, six published tags. The mode is chosen at run time (or baked into the tag at build time).

This page walks through every mode, with copy-paste examples that work without any other Mockarty component.

TL;DR

# Pull the universal image and pick a mode by subcommand:
docker run --rm -p 8080:8080 mockarty/cli:latest mock serve

# Or pull the mode-specific tag — the subcommand is baked in, pass only
# its arguments and flags:
docker run --rm -p 8080:8080 mockarty/cli:latest-mock
docker run --rm -v $PWD/k6.js:/k6.js mockarty/cli:latest-load /k6.js --vus 10 --duration 30s
docker run --rm -v $PWD/manifest.yaml:/m.yaml mockarty/cli:latest-test /m.yaml

All six tags are built from the same binary and base: same multi-arch (linux/amd64 + linux/arm64) build. The only difference is the baked-in command.

Image tags

On a mode-specific tag the command is part of the image’s entrypoint: anything you pass after the image name is appended to it (positional arguments and flags), so mockarty/cli:latest-load /k6.js --vus 10 runs perf run /k6.js --vus 10. To run a different subcommand, use the generic tag.

Mocker mode — drop-in WireMock/Mockoon replacement

mock serve starts an in-process HTTP server with both the WireMock admin API and the native Mockarty admin API. Stubs are loaded from --data-dir at startup; new stubs can be POSTed at run time. Auto-detection lets you mix WireMock, Mockoon and Mockarty native JSON in the same directory.

docker run --rm -p 8080:8080 \
    -v $PWD/stubs:/data:ro \
    mockarty/cli:latest-mock \
    --data-dir /data

Inside the container the server listens on 0.0.0.0:8080 by default — no extra flags needed.

WireMock-compatible admin API

curl -X POST http://localhost:8080/__admin/mappings \
    -H 'Content-Type: application/json' \
    -d '{"request":{"method":"GET","url":"/api/users"},"response":{"status":200,"body":"{\"ok\":true}"}}'

curl http://localhost:8080/api/users
# → 200 {"ok":true}

Native Mockarty admin API

Also available at the same port:

Use this API when you want chains, faker, JsonPath and store features — they all work in standalone mode without an admin node.

Anonymous-mode limits

When you run the container without a license (no --api-key + --license-server, no MOCKARTY_LICENSE_KEY env), the in-memory stub catalogue is capped at 5 stubs. The 6th POST /__admin/mappings returns HTTP 402 with a hint to authenticate.

To unlock the full surface, configure a license:

docker run --rm -p 8080:8080 \
    -e MOCKARTY_LICENSE_KEY=<your-token> \
    mockarty/cli:latest-mock

Load-runner mode

The script path is positional (k6-style). The target URL lives inside the script — pass it via a k6-compatible env var (__ENV.BASE_URL in the script):

docker run --rm \
    -v $PWD/scripts:/scripts:ro \
    -v $PWD/reports:/reports \
    mockarty/cli:latest-load \
    /scripts/load.js \
    --env BASE_URL=https://api.example.com \
    --vus 50 \
    --duration 5m \
    --out json:/reports/load.json

Container exits with code 0 on success, non-zero on threshold failures — wires cleanly into CI.

Test-runner mode

The -test tag runs a Mockarty-native test manifest (the path is positional):

docker run --rm \
    -v $PWD/tests:/tests:ro \
    -v $PWD/reports:/reports \
    mockarty/cli:latest-test \
    /tests/manifest.yaml \
    --out junit:/reports/junit.xml

For Postman/Newman collections use the generic tag with an explicit postman run (the collection path is positional):

docker run --rm \
    -v $PWD/collections:/collections:ro \
    -v $PWD/reports:/reports \
    mockarty/cli:latest \
    postman run /collections/api.json \
    --out allure:/reports/allure \
    --out junit:/reports/junit.xml

Fuzz-runner mode

docker run --rm \
    -v $PWD/api.yaml:/api.yaml:ro \
    mockarty/cli:latest-fuzz \
    --spec /api.yaml \
    --target https://api.example.com \
    --duration 60s

Chaos-runner mode

Chaos requires a Mockarty admin server (the experiment is executed there):

docker run --rm \
    -e MOCKARTY_SERVER=https://mockarty.company.com \
    -e MOCKARTY_TOKEN=mk_xxx \
    -v $PWD/experiments:/experiments:ro \
    mockarty/cli:latest-chaos \
    -f /experiments/network-blip.yaml

Or describe the experiment entirely with flags — for example --type pod_kill --namespace app --selector app=web --duration 5m.

Hardening

• Distroless static base image (≈10 MB + binary)
• nonroot user (UID 65532)
• Statically linked — no glibc dependency
• Read-only root filesystem compatible (mount tmpfs at /tmp if you need writes)
• No CDN fetches at runtime — fully air-gapped friendly

Multi-arch

Official images are published for both linux/amd64 and linux/arm64 from the
same release, so Apple Silicon and AWS Graviton are first-class.

docker-compose example

A turn-key multi-service setup is straightforward — run the CLI container
alongside load and test-runner containers, each using the published image:

services:
  mocker:
    image: mockarty/cli:latest-mock
    command: ["--data-dir", "/data"]
    volumes: ["./mocks:/data:ro"]
    ports: ["8080:8080"]

A complete three-service example (mock server + load runner + test runner wired together) ships with the CLI sources as docker-compose.example.yml.

Testcontainers integration

Java / Python / Go SDK testcontainers wrappers all point at mockarty/cli:latest-mock by default. From your test code:

# Python
from mockarty.testcontainers import MockartyContainer
with MockartyContainer() as mock:
    mock.add_stub({"request": {"method":"GET","url":"/x"}, "response":{"status":200,"body":"ok"}})
    resp = requests.get(f"{mock.base_url}/x")

// Java
try (MockartyContainer mock = new MockartyContainer()) {
    mock.addStub("...");
    String body = HttpClient.get(mock.baseUrl() + "/x").body();
}

The wrapper pulls mockarty/cli:latest-mock, exposes 8080, and tears down on close(). See the SDK READMEs for the full reference.