run-mx

Run Mendix Studio Pro apps from the command line. No Studio required.

Independent open-source tool. Not affiliated with or endorsed by Mendix Technology B.V. "Mendix" is a trademark of Mendix Technology B.V. and is used here only to identify the platform this tool works with.

run-mx dev is the equivalent of Studio's Run Locally — it builds the model with mxbuild, bundles the web client with the Rollup that ships inside Studio, and launches the runtime — all from the terminal. Works with Mendix 8, 9, 10, and 11 by auto-detecting the project's version and picking the matching JDK.

Windows-only. Mendix Studio Pro is Windows-only, so the install layout run-mx discovers only exists on Windows.

Install

npm install -g run-mx

Requirements:

• Node.js ≥ 18
• A Mendix Studio Pro install at C:\Program Files\Mendix\<version> (no Studio launch needed — run-mx uses its bundled mxbuild, rollup, and runtime)
• A JDK matching your Mendix major version (8→Java 8, 9→11, 10→17, 11→21). If missing, run-mx prints the winget command to install it.

Usage

Run from your Mendix project directory (the one with BasicApp.mpr or similar):

run-mx dev              # build + bundle + run + rollup --watch    (replaces Studio "Run Locally")
run-mx start            # launch runtime against an existing build (fast re-launch)
run-mx clean            # remove deployment/{model,run,web/dist}
run-mx info             # project, toolchain, build, and runtime status (--json for scripting)
run-mx update-widgets   # sync widgets/*.mpk into the .mpr (wraps `mx update-widgets`)
run-mx pack             # export project as a .mpk package (wraps `mx create-project-package`)

update-widgets writes to the .mpr. Close Studio Pro for this project before running it — the file is a SQLite DB and Studio holds locks while open.

pack is also available as run-mx create-project-package. Useful flags: --out-dir <dir>, --include-snapshot, --skip-managed-dependency-sync.

Open http://localhost:8080 once you see Container start took ... in the log.

Options

| Flag | Default | What | |---|---|---| | -p, --project <path> | auto-detect | Path to the .mpr file (only needed if there are multiple in the cwd) | | --mx-version <x.y.z> | from .mpr | Pin the Mendix install version | | --mx-install <path> | from version | Full path to a Mendix install root | | --java-home <path> | auto-detect | Override the JDK home | | --port <n> | 8080 | Runtime HTTP port | | --admin-port <n> | 8090 | m2ee admin port | | --no-watch | (dev only) | Bundle once, don't keep rollup running | | --db-type <type> | from project | Override DB type (PostgreSQL, MySQL, SQLSERVER, ORACLE, HSQLDB) | | --db-host <host[:port]> | from project | DB host (and port) | | --db-name <name> | from project | DB name / schema | | --db-user <user> | from project | DB username | | --db-pass <pwd> | from project | DB password | | --db-jdbc-url <url> | from project | Full JDBC URL — overrides --db-type/host/name |

The --db-* flags are forwarded to the runtime as MX_Database* environment variables, so they override whatever DB the project's active configuration would have used. Useful when Studio Pro keeps the password in the Windows credential vault (the runtime can't see it) or when you want to point a project at a different DB without editing the configuration.

run-mx dev --db-type PostgreSQL --db-host db.local:5432 --db-name myapp --db-user myapp --db-pass s3cret

Set RUN_MX_DEBUG=1 to print stack traces on failure.

Error handling

When mxbuild rejects the model (broken microflow, missing entity, bad page binding, etc.), run-mx parses mxbuild's --write-errors JSON and prints a tight summary:

✗ 3 mxbuild errors:
  • MyModule.OnClick_Save      Microflow references missing entity 'OldTask'
  • Atlas_Core.Layout_Sidebar  Page has invalid widget configuration
  • MyModule.Customer          Attribute 'Email' has no length set
✗ mxbuild failed — 3 model errors. See the report above.

Warnings/deprecations (non-fatal problems[]) print in yellow without aborting the build. Rollup and runtime errors stream through to your terminal verbatim — those tools already format their own output well.

How it works

Studio Pro's "Run Locally" does four things; run-mx does the same four, headlessly:

1. mxbuild --target=deploy --java-home=… --java-exe-path=… — compiles the .mpr into deployment/model/ and runs the Gradle steps to compile custom Java actions.
2. rollup -c inside deployment/web/ — bundles the modern web client into deployment/web/dist/. Uses the Node + Rollup that ship inside the Mendix install (modeler\tools\node\…), so you don't need a project-local node_modules.
3. java -cp runtimelauncher.jar com.mendix.container.boot.Main <deployment> — boots the runtime container and m2ee admin server. Env vars (M2EE_ADMIN_PASS, MXCONSOLE_*) match Studio's launch contract.
4. MendixConsoleLog.exe — the runtime auto-spawns it (because M2EE_CONSOLE_PATH is set), and it issues the m2ee admin calls that actually start the app on :8080.

Ctrl+C cleanly stops the Java runtime, the rollup watcher, and MendixConsoleLog.exe.

License

MIT