mule-headless-dev

Run, deploy, and iterate on a MuleSoft (Mule 4) app on a real local runtime without Anypoint Studio — a headless build → deploy → test loop for fast, scriptable Mule development. Cross-platform: Windows, macOS, Linux.

Packaged as a Claude Code skill, but the scripts work standalone too.

What's inside

• SKILL.md — the guide: mental model, the iterate loop, platform specifics, hot-redeploy vs full restart.
• scripts/ — setup, start, stop, restart, redeploy, each in both .sh (macOS/Linux) and .ps1 (Windows). All parameterized — no hardcoded paths.
• references/troubleshooting.md — symptom → fix catalog, including the common DataWeave / Mule authoring foot-guns (reserved words, the output directive, non-Core imports, YAML quoting, Object-Store defaults, http:request child order).

Prerequisites

• JDK 17 — Mule 4.9+ requires it; the scripts auto-detect one (or set MULE_JDK17).
• Maven 3.9+.
• Anypoint EE credentials in ~/.m2/settings.xml — the same creds that build a Mule app; needed to download the EE runtime and resolve EE connectors. If you can already mvn clean package a Mule project, you have these. Setting up fresh from Support-provided Nexus creds? settings.xml needs both the EE Nexus repo and the public MuleSoft repos — building an app pulls a runtime classpath split across the two (com.mulesoft.* from releases-ee, org.mule.runtime:* like mule-dwb-api from public). See Credentials & settings.xml below for which credential goes where (and references/troubleshooting.md §8).

Credentials & settings.xml

The runtime distribution and EE artifacts are not on a public repo, and the credentials are not your Anypoint Platform SSO login. A working ~/.m2/settings.xml declares three repos, each with a different credential:

Artifacts	Repo	Credential
Runtime distribution + com.mulesoft.mule.runtime:* (EE)	EE Nexus …/nexus-ee/content/repositories/releases-ee/	Support-provisioned Nexus enterprise creds — tied to a paid subscription, not Anypoint SSO
com.mulesoft.connectors:* (Einstein, premium connectors) + your org's Exchange assets	Anypoint Exchange v3 maven.anypoint.mulesoft.com/api/v3/maven	Connected App (username = ~~~Client~~~, password = <clientId>~?~<clientSecret>)
org.mule.runtime:* (public, e.g. mule-api, mule-dwb-api)	Public repository.mulesoft.org/nexus/content/repositories/public/	none

No EE Nexus creds? They're provisioned through MuleSoft Support / your CSM (open a case for "Enterprise Maven repository credentials") against your subscription. Your Anypoint SSO and a Connected App both legitimately 401 against releases-ee — it's a separate credential system, by design.

Minimal ~/.m2/settings.xml — the <server> id MUST match the <repository> id it authenticates:

<settings>
  <servers>
    <server>                                  <!-- EE Nexus: distribution + EE runtime jars -->
      <id>MuleRepository</id>
      <username>YOUR_EE_NEXUS_USER</username>
      <password>YOUR_EE_NEXUS_PASS</password>
    </server>
    <server>                                  <!-- Anypoint Exchange v3: connectors + org assets -->
      <id>anypoint-exchange-v3</id>
      <username>~~~Client~~~</username>
      <password>YOUR_CONNECTED_APP_CLIENT_ID~?~YOUR_CONNECTED_APP_CLIENT_SECRET</password>
    </server>
  </servers>
  <profiles>
    <profile>
      <id>Mule</id>
      <repositories>
        <repository><id>MuleRepository</id>
          <url>https://repository.mulesoft.org/nexus-ee/content/repositories/releases-ee/</url>
          <releases><enabled>true</enabled></releases></repository>
        <repository><id>mulesoft-public</id>
          <url>https://repository.mulesoft.org/nexus/content/repositories/public/</url></repository>
        <repository><id>anypoint-exchange-v3</id>
          <url>https://maven.anypoint.mulesoft.com/api/v3/maven</url></repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository><id>MuleRepository</id>
          <url>https://repository.mulesoft.org/nexus-ee/content/repositories/releases-ee/</url></pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>
  <activeProfiles><activeProfile>Mule</activeProfile></activeProfiles>
</settings>

If you can already mvn clean package a Mule app from the CLI, you have all three and setup reuses the same settings.xml. (Studio users: copy the settings.xml Studio generated.)

Install — as a Claude Code skill

Clone straight into your skills directory — the repo name matches the skill, so no rename is needed:

git clone https://github.com/chirstius/mule-headless-dev ~/.claude/skills/mule-headless-dev

That makes it available in every project. For a single project instead, clone into <your-project>/.claude/skills/mule-headless-dev. Either way, Claude uses it whenever you ask it to run, redeploy, smoke-test, or stand up a Mule app locally. (Prefer a zip? Grab a release and drop the mule-headless-dev/ folder in the same place.)

The .sh scripts are committed with the executable bit set, so a git clone leaves them runnable on macOS/Linux with no extra step. (A downloaded zip can't carry that bit — see the standalone section.)

Install — standalone (no Claude)

Just run the scripts directly. On macOS/Linux, make them executable once — a zip created on Windows can't carry the Unix +x bit:

chmod +x scripts/*.sh

(Or invoke them as bash scripts/start.sh without changing the bit.)

Quick start

# 1) one-time: download + configure a clean standalone runtime
MULE_VERSION=4.11.4 DEST_PARENT="$HOME/mule-ee" scripts/setup.sh

# 2) point at the runtime and start it
export MULE_RUNTIME="$HOME/mule-ee/mule-enterprise-standalone-4.11.4"
scripts/start.sh

# 3) from your Mule project dir: build + hot-redeploy, then iterate
export MULE_PROJECT="$(pwd)"
scripts/redeploy.sh                 # optional: pass an app health URL as arg 1
#   edit code → scripts/redeploy.sh → test → repeat
#   if a hot-redeploy looks stale:  scripts/restart.sh   (full clean redeploy)
scripts/stop.sh                     # stop when done

Windows: use the matching scripts\*.ps1 under PowerShell (not Git-Bash — MSYS rewrites /-leading paths; see SKILL.md / troubleshooting §12). Settings come from env vars (MULE_RUNTIME, MULE_PROJECT, MULE_JDK17) or flags; run any script with -h/--help or read its header.

Cross-platform notes

• .sh scripts are bash-3.2-safe (stock macOS) and avoid GNU-only idioms (portable sed -i.bak, tail -n +N, seq, curl -w %{http_code}; no readlink -f).
• JDK 17 detection covers macOS (/usr/libexec/java_home -v 17) and Linux (sdkman / /usr/lib/jvm / apt).
• Windows runtime control is console-under-a-background-shell — the Windows service path hits the SCM ~30 s start timeout (troubleshooting §6). Unix mule start daemonizes cleanly.

Troubleshooting

See references/troubleshooting.md. The single most useful reflex: when in doubt, full restart (§1). Also covers wrong-runtime deploys (§11), wrong-JDK errors (§5), boot timeouts (§3), Object-Store state leakage (§2), and the DataWeave/config authoring foot-guns (§13).