Documentation Core Concepts Environments Services Reactions Reaction Examples Variables Mock Accounts Script Library & JWT Attachments LDAP Mode Forwarding & Recording CORS & Auth Basics MCP & REST API Clustering & Clones Administration Debug & Troubleshooting

Clustering & Clones AI-generated

A single MockMotor instance can be scaled out as one Admin instance plus any number of read-mostly Clone instances, kept in sync over a private JGroups cluster channel. Clones serve real mock traffic and replicate everything from the admin; configuration changes are made on the admin and propagate out.

Cluster settings

Under Settings → Cluster, the admin instance exposes:

  • Admin Instance Host / Port - the address clones connect to (default port 7082).
  • Current Cluster Size - how many nodes are currently connected.
  • Cluster Authentication - whether a join token is set, plus a Regenerate Cluster Join Token button.
Regenerating the token is disruptive by design. It immediately invalidates the current token; every already-running clone can no longer rejoin until it's given the new token and restarted. Use it when rotating credentials after a suspected leak, not casually.

Cluster join token: authentication and encryption

When a join token is configured, it secures the cluster channel two ways at once, from one shared secret:

  • Membership (AUTH) - a node must present a matching token to be allowed to join the group at all; simply being able to reach the cluster port is no longer sufficient.
  • Encryption (SYM_ENCRYPT) - an AES-256 key deterministically derived from the same token encrypts all cluster traffic, including the AUTH handshake itself.

Leaving the token unset keeps the legacy behavior: an unauthenticated, unencrypted cluster channel. This is the default for upgraded installs so existing fleets aren't broken by a jar update alone - set a token deliberately to opt in.

Provisioning a clone

There's no button for this in the console - a clone package is fetched with a script, by calling the admin's /console/clone endpoint over HTTPS with an admin API key. The response is a .tgz bundling a config file pre-filled with the admin's host/port, the current cluster join token, the TLS identity, and start/stop/update shell scripts - unpack it on the new box and run startMockMotor.sh. The act of provisioning a clone this way also opts an existing, pre-token fleet into cluster authentication automatically - the first clone package generated after upgrading turns it on for everyone.

curl -sS --fail \
  -H "X-MockMotor-API-Key: mm_ADMIN_API_KEY_GOES_HERE" \
  -o mockmotor-clone.tgz \
  "https://admin.example.com:7081/console/clone"

tar xzf mockmotor-clone.tgz
./startMockMotor.sh

The endpoint requires HTTPS and is rate-limited per source IP; the API key must belong to an admin user to get the full package (config + start/stop/update scripts), not just the jar.

What replicates

Environments, services, reactions, accounts, variables and attachments all replicate from admin to clones. A clone answers real mock traffic identically to the admin; administrative changes (adding a service, editing a reaction) are made on the admin only and flow outward.

See also: Environments Administration