@rainbow-robotics/muscat-plugin-kit 1.3.2 → 1.3.3

package/cli/docker/Dockerfile.cpp

@@ -10,18 +10,35 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       cmake \
     && rm -rf /var/lib/apt/lists/*
 
-# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
-# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
-# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Rainbow Robotics C++ SDK for find_package(rb_sdk).
 # Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.2~dev1
+ARG RB_SDK_VERSION=0.1.3
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
-    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
     && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/docker/Dockerfile.dev

@@ -9,18 +9,38 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
       python3-colcon-common-extensions \
     && rm -rf /var/lib/apt/lists/*
 
-# Rainbow Robotics C++ SDK (rainbow-rb-sdk-dev): headers + CMake config for
-# find_package(rb_sdk). Pinned to the robot's SDK version — the binary links
-# librb_sdk.so.<ver> by SONAME and the robot provides that exact .so at runtime.
+# Rainbow Robotics C++ SDK for find_package(rb_sdk).
 # Override with MUSCAT_PK_RB_SDK_VERSION=<ver> (+ MUSCAT_PK_REBUILD_IMAGE=1).
-ARG RB_SDK_VERSION=0.1.2~dev1
+ARG RB_SDK_VERSION=0.1.3
 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl \
     && install -d /etc/apt/keyrings \
     && curl -fsSL https://rainbowrobotics.github.io/rb-sdk/rb-sdk-apt-repo.gpg.key -o /etc/apt/keyrings/rb-sdk.asc \
-    && echo 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk dev main' > /etc/apt/sources.list.d/rb-sdk.list \
+    && printf 'deb [signed-by=/etc/apt/keyrings/rb-sdk.asc] https://rainbowrobotics.github.io/rb-sdk %s main\n' stable dev > /etc/apt/sources.list.d/rb-sdk.list \
     && apt-get update && apt-get install -y --no-install-recommends "rainbow-rb-sdk-dev=${RB_SDK_VERSION}" \
     && rm -rf /var/lib/apt/lists/*
 
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
+
+# `docker exec` skips /ros_entrypoint.sh — source ROS for the login shells dev:back runs.
+RUN echo ". /opt/ros/${ROS_DISTRO}/setup.sh" > /etc/profile.d/ros.sh
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/docker/Dockerfile.python

@@ -15,6 +15,25 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 # cpp SDK shared lib must be present for the python module to load. Install the
 # rainbow cpp SDK (apt, pinned to the robot's version) here once it exists.
 
+# MediaMTX — same version/ports as the Muscat runtime (rby2 scripts/backend/runtime/mediamtx.yml),
+# plus webrtcAdditionalHosts so a browser on the dev host reaches the WebRTC media port.
+ARG MEDIAMTX_VERSION=1.12.3
+RUN set -eux; \
+    apt-get update; apt-get install -y --no-install-recommends ca-certificates curl; rm -rf /var/lib/apt/lists/*; \
+    case "$(uname -m)" in x86_64) a=amd64 ;; aarch64|arm64) a=arm64 ;; *) exit 1 ;; esac; \
+    curl -fsSL "https://github.com/bluenviron/mediamtx/releases/download/v${MEDIAMTX_VERSION}/mediamtx_v${MEDIAMTX_VERSION}_linux_${a}.tar.gz" \
+      | tar -xz -C /usr/local/bin mediamtx; \
+    mkdir -p /etc/mediamtx; \
+    printf '%s\n' \
+      'logLevel: warn' \
+      'rtsp: yes' 'rtspAddress: :8554' \
+      'webrtc: yes' 'webrtcAddress: :8889' \
+      'webrtcLocalUDPAddress: :8189' 'webrtcLocalTCPAddress: :8189' \
+      'webrtcAdditionalHosts: [127.0.0.1]' 'webrtcAllowOrigin: "*"' \
+      'hls: no' 'rtmp: no' 'srt: no' 'api: no' \
+      'paths:' '  all_others:' '    source: publisher' \
+      > /etc/mediamtx/mediamtx.yml
+
 WORKDIR /plugin
 
 CMD ["bash"]

package/cli/src/bridge.mjs

@@ -8,6 +8,8 @@ import { createServer, connect } from "node:net";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { canSkipImageBuild, hasBin, kitRoot, log, pruneMuskatImages } from "./util.mjs";
+import { MEDIA_PORTS, mediaPortFlags } from "./ports.mjs";
+import { usesHostNetwork } from "./zenohDev.mjs";
 
 export const BRIDGE_IMAGE = "muscat-pk-bridge";
 export const BRIDGE_CONTAINER = "muscat-pk-bridge-run";
@@ -63,9 +65,16 @@ function ensureImage() {
   pruneMuskatImages();
 }
 
+/** A running Muscat container (e.g. muscat-dev) that owns host port 10000, or null. */
+export function localMuscatContainer() {
+  const r = spawnSync("docker", ["ps", "--filter", `publish=${BRIDGE_PORT}`, "--format", "{{.Names}}"], { encoding: "utf8" });
+  return (r.stdout || "").split("\n").map((n) => n.trim()).find((n) => n && n !== BRIDGE_CONTAINER) ?? null;
+}
+
 /**
  * Build the image, preflight the port, and start the bridge container.
- * Returns true if bridge started, false if port was already in use (caller decides).
+ * Returns false if port 10000 was already in use (caller decides), else { media }:
+ * whether the MediaMTX ports are free for the backend's own MediaMTX.
  */
 export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   assertDockerReady();
@@ -88,6 +97,13 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   }
   const publishable = pluginPorts.filter((port) => !busy.includes(port));
 
+  const mediaBusy = [];
+  for (const port of MEDIA_PORTS) {
+    if (await isPortInUse(port)) mediaBusy.push(port);
+  }
+  const media = mediaBusy.length === 0;
+  if (!media) log.warn(`MediaMTX port(s) already in use: ${mediaBusy.join(", ")} — video streaming disabled in dev.`);
+
   ensureImage();
 
   log.step("starting Socket.IO bridge container…");
@@ -98,6 +114,7 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
     "-p", `127.0.0.1:${BRIDGE_PORT}:${BRIDGE_PORT}`,
     ...(zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : []),
     ...publishable.flatMap((port) => ["-p", `127.0.0.1:${port}:${port}`]),
+    ...(media && !usesHostNetwork() ? mediaPortFlags() : []),
   ];
   const up = spawnSync(
     "docker",
@@ -111,7 +128,7 @@ export async function startBridge({ zenohPort = null, pluginPorts = [] } = {}) {
   if (zenohPort) log.step(`Zenoh dev peer port published on :${zenohPort}`);
   if (publishable.length > 0)
     log.step(`plugin backend ports published on 127.0.0.1: ${publishable.join(", ")}`);
-  return true;
+  return { media };
 }
 
 export function stopBridge() {

package/cli/src/build.mjs

@@ -75,33 +75,19 @@ function runViteBuild(pluginRoot, { mode = "production" } = {}) {
 // rclpy: arch-agnostic (pure Python) → dist/ros2_ws/install/ (built once)
 // rclcpp: arch-specific C++ binaries → dist/ros2_ws/install-{arch}/ per arch
 export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "ros2") return [];
+  if (manifestRuntime(root) !== "ros2") return;
   const { assertDockerReady, ensureImage, colconBuild, ROS2_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./ros2.mjs");
-  try {
-    assertDockerReady();
-  } catch (e) {
-    log.warn(`ros2 build skipped: ${e.message}`);
-    return [];
-  }
+  assertDockerReady();
 
   const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8"));
-  const rosClient = manifest.runtime?.rosClient;
-
-  const skipped = [];
-  if (rosClient === "rclcpp") {
+  if (manifest.runtime?.rosClient === "rclcpp") {
     // C++ ROS2: compile per arch so each robot picks the right install-{arch}/
     for (const arch of archs) {
       const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-      if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
-      const archImage = `${ROS2_DEV_IMAGE}-${arch}`;
-      try {
-        await ensureImage(archImage, { platform: dockerPlatform });
-        colconBuild(root, { symlink: false, arch });
-        log.ok(`dist/ros2_ws/install-${arch}/ ready`);
-      } catch {
-        log.warn(`${arch} ros2 build skipped — QEMU not available`);
-        skipped.push(arch);
-      }
+      if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+      await ensureImage(`${ROS2_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+      colconBuild(root, { symlink: false, arch });
+      log.ok(`dist/ros2_ws/install-${arch}/ ready`);
     }
   } else {
     // rclpy / pure Python: arch-agnostic, build once
@@ -109,54 +95,37 @@ export async function exportRos2Build(root, archs = ["amd64", "arm64"]) {
     colconBuild(root, { symlink: false });
     log.ok("dist/ros2_ws/install/ ready");
   }
-  return skipped;
 }
 
 // For cpp plugins, compile cpp/ inside the Ubuntu container (Release) per arch
 // and copy each binary into dist/{arch}/{entry} so the ZIP carries relocatable
-// robot-compatible executables. rb-runtime prefers dist/{arch}/ and falls back
-// to dist/{entry} (legacy). Skipped (with a warning) if Docker is unavailable.
+// robot-compatible executables.
 export async function exportCppBuild(root, distDir, archs = ["amd64", "arm64"]) {
-  if (manifestRuntime(root) !== "cpp") return [];
+  if (manifestRuntime(root) !== "cpp") return;
   const { assertDockerReady, ensureImage, cmakeBuild, CPP_DEV_IMAGE, ARCH_DOCKER_PLATFORM } = await import("./cpp.mjs");
-  try {
-    assertDockerReady();
-  } catch (e) {
-    log.warn(`cpp build skipped: ${e.message}`);
-    return [];
-  }
+  assertDockerReady();
 
   const entry = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime?.entry;
-  if (!entry) {
-    log.warn("manifest.json runtime.entry not set — cpp build skipped");
-    return;
-  }
+  if (!entry) throw new Error("manifest.json runtime.entry is required for cpp (the built executable name)");
 
-  const skipped = [];
   for (const arch of archs) {
     const dockerPlatform = ARCH_DOCKER_PLATFORM[arch];
-    if (!dockerPlatform) { log.warn(`unknown arch '${arch}' — skipped`); skipped.push(arch); continue; }
-    const archImage = `${CPP_DEV_IMAGE}-${arch}`;
-    try {
-      await ensureImage(archImage, { platform: dockerPlatform });
-      cmakeBuild(root, { buildType: "Release", arch });
-      const built = resolve(root, `cpp/build-${arch}`, entry);
-      if (existsSync(built)) {
-        const archDir = resolve(distDir, arch);
-        mkdirSync(archDir, { recursive: true });
-        const dest = resolve(archDir, entry);
-        copyFileSync(built, dest);
-        chmodSync(dest, 0o755);
-        log.ok(`cpp binary → dist/${arch}/${entry}`);
-      } else {
-        log.warn(`cpp binary not found at cpp/build-${arch}/${entry}`);
-      }
-    } catch {
-      log.warn(`${arch} cpp build skipped — QEMU not available`);
-      skipped.push(arch);
+    if (!dockerPlatform) throw new Error(`unknown arch '${arch}'`);
+    await ensureImage(`${CPP_DEV_IMAGE}-${arch}`, { platform: dockerPlatform });
+    cmakeBuild(root, { buildType: "Release", arch });
+    const built = resolve(root, `cpp/build-${arch}`, entry);
+    if (!existsSync(built)) {
+      throw new Error(`cpp/build-${arch}/${entry} not found — the CMake target name must equal runtime.entry`);
     }
+    const archDir = resolve(distDir, arch);
+    mkdirSync(archDir, { recursive: true });
+    const dest = resolve(archDir, entry);
+    copyFileSync(built, dest);
+    chmodSync(dest, 0o755);
+    const libDir = resolve(root, `cpp/build-${arch}`, "lib");
+    if (existsSync(libDir)) cpSync(libDir, resolve(archDir, "lib"), { recursive: true, verbatimSymlinks: true });
+    log.ok(`cpp binary → dist/${arch}/${entry}${existsSync(libDir) ? " (+ lib/)" : ""}`);
   }
-  return skipped;
 }
 
 const PRERELEASE_RE = /\.(dev|a|b|rc|alpha|beta)\d*/i;
@@ -426,11 +395,12 @@ export async function runBuild(args) {
 
   await promptVersion(root);
   const archs = await promptArch(args);
+  // Drop a previous ZIP of this version so a failed build can't leave a stale one to upload.
+  const version = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).version || "0.0.0";
+  rmSync(resolve(root, `${basename(root)}-${version}.zip`), { force: true });
 
   const { pluginRoot, distDir } = await buildPlugin({ root, minify: true });
 
-  const skippedArches = { wheels: [], ros2: [], cpp: [] };
-
   // python / rclpy: lock + wheel vendor in Ubuntu 24.04 container
   if (!noLock) {
     const manifest = JSON.parse(readFileSync(resolve(root, "manifest.json"), "utf8")).runtime ?? {};
@@ -439,30 +409,12 @@ export async function runBuild(args) {
       (manifest.type === "ros2" && manifest.rosClient === "rclpy");
     if (needsLock) {
       const { lockAndVendor } = await import("./python.mjs");
-      try {
-        skippedArches.wheels = await lockAndVendor(pluginRoot, archs);
-      } catch (e) {
-        log.warn(`python lock/vendor skipped: ${e.message}`);
-        skippedArches.wheels = archs;
-      }
+      await lockAndVendor(pluginRoot, archs);
     }
   }
 
-  skippedArches.ros2 = await exportRos2Build(root, archs) ?? [];
-  skippedArches.cpp  = await exportCppBuild(root, distDir, archs) ?? [];
+  await exportRos2Build(root, archs);
+  await exportCppBuild(root, distDir, archs);
   calcInstalledSize(pluginRoot);
   if (!noZip) packZip(pluginRoot);
-
-  // Build summary
-  const allSkipped = [...new Set([...skippedArches.wheels, ...skippedArches.ros2, ...skippedArches.cpp])];
-  if (allSkipped.length > 0) {
-    const line = "─".repeat(58);
-    console.log(`\n${line}`);
-    log.warn(`Cross-arch builds skipped (QEMU not available): ${allSkipped.join(", ")}`);
-    if (skippedArches.wheels.length) log.warn(`  wheels:  ${skippedArches.wheels.join(", ")}`);
-    if (skippedArches.ros2.length)   log.warn(`  ros2:    ${skippedArches.ros2.join(", ")}`);
-    if (skippedArches.cpp.length)    log.warn(`  cpp:     ${skippedArches.cpp.join(", ")}`);
-    log.warn(`  Enable: docker run --privileged --rm tonistiigi/binfmt --install all`);
-    console.log(line);
-  }
 }

package/cli/src/cpp.mjs

@@ -3,7 +3,7 @@
 // Used by dev:back (interactive dev loop) and build (export the binary into the ZIP).
 import { spawnSync } from "node:child_process";
 import { dirname } from "node:path";
-import { canSkipImageBuild, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
+import { canSkipImageBuild, imageKey, imageKeyLabel, dockerUserFlags, hasBin, log, pruneMuskatImages, resolveDockerfile } from "./util.mjs";
 
 export const CPP_DEV_IMAGE = "muscat-pk-cpp-dev";
 
@@ -15,15 +15,16 @@ export function assertDockerReady() {
 
 /** Build the dev image from the kit's bundled Dockerfile (Docker layer-caches). */
 export async function ensureImage(image = CPP_DEV_IMAGE, { platform = null } = {}) {
-  if (canSkipImageBuild(image)) {
+  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
+  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
+  const key = imageKey(dockerfile, sdkVer ?? "");
+  if (canSkipImageBuild(image, key)) {
     log.step(`${image} already built — skipping docker build`);
     return;
   }
-  const dockerfile = await resolveDockerfile("Dockerfile.cpp");
   log.step(`docker build -t ${image}${platform ? ` (${platform})` : ""} (first run is slow, then cached)…`);
   const platformFlags = platform ? ["--platform", platform] : [];
-  const sdkVer = process.env.MUSCAT_PK_RB_SDK_VERSION;
-  const buildArgs = sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : [];
+  const buildArgs = [...(sdkVer ? ["--build-arg", `RB_SDK_VERSION=${sdkVer}`] : []), ...imageKeyLabel(key)];
   const r = spawnSync(
     "docker",
     ["build", ...platformFlags, ...buildArgs, "-t", image, "-f", dockerfile, dirname(dockerfile)],
@@ -52,9 +53,12 @@ export function cmakeBuild(root, { image = CPP_DEV_IMAGE, buildType = "Debug", a
   const platformFlags = dockerPlatform ? ["--platform", dockerPlatform] : [];
   // arch 빌드 시 arch별 이미지 사용 (로컬 이미지와 platform 불일치 방지)
   const actualImage = arch ? `${CPP_DEV_IMAGE}-${arch}` : image;
+  // Export builds ship lib/ next to the binary: librb_sdk.so (robot has no SDK) + any .so the
+  // plugin copied there itself. Found via RPATH $ORIGIN/lib.
   const script = [
-    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}`,
+    `cmake -S cpp -B ${buildDir} -DCMAKE_BUILD_TYPE=${buildType}` + (arch ? ` -DCMAKE_BUILD_RPATH='$ORIGIN/lib'` : ""),
     `cmake --build ${buildDir} -j`,
+    ...(arch ? [`rm -f ${buildDir}/lib/librb_sdk.so.* && if readelf -d $(find ${buildDir} -maxdepth 1 -type f -executable) 2>/dev/null | grep -q librb_sdk; then mkdir -p ${buildDir}/lib && cp -a $(dpkg -L rainbow-rb-sdk | grep -E '/librb_sdk[.]so[.][0-9]') ${buildDir}/lib/; fi`] : []),
   ].join(" && ");
   const label = arch ? `cmake build (${buildType}, ${arch}, in container)…` : `cmake build (${buildType}, in container)…`;
   log.step(label);

package/cli/src/dev.mjs

@@ -6,7 +6,7 @@ import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { runDevUi } from "./devUi.mjs";
 import { runDevBack, stopDevBackContainers } from "./devBack.mjs";
-import { startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
+import { localMuscatContainer, startBridge, stopBridge, BRIDGE_CONTAINER, BRIDGE_PORT } from "./bridge.mjs";
 import { assertManifestPorts, assertManifestVariables } from "./manifest.mjs";
 import { formatPortRanges } from "./ports.mjs";
 import {
@@ -138,7 +138,11 @@ export async function runDev(args = []) {
     pluginPorts: usesHostNetwork() ? [] : portRanges,
   });
 
-  if (!bridgeStarted) {
+  const muscat = bridgeStarted ? null : localMuscatContainer();
+  if (muscat) {
+    log.step(`local Muscat container '${muscat}' owns :${BRIDGE_PORT} — backend joins its network (gateway, MediaMTX)`);
+    process.env.MUSCAT_PK_MUSCAT_CONTAINER = muscat;
+  } else if (!bridgeStarted) {
     log.warn(`port ${BRIDGE_PORT} is already in use — can't start Socket.IO bridge.`);
     const answer = await prompt("  Proceed without Socket.IO bridge? [y/N]: ");
     if (answer.toLowerCase() !== "y") return;
@@ -147,6 +151,7 @@ export async function runDev(args = []) {
     // Tell dev:back which bridge container to share a netns with, so the backend
     // reaches the bridge at localhost:10000 (no host.docker.internal).
     process.env.MUSCAT_PK_BRIDGE_CONTAINER = BRIDGE_CONTAINER;
+    if (bridgeStarted.media) process.env.MUSCAT_PK_MEDIA = "1";
   }
 
   process.env.MUSCAT_PK_MANAGED_DEV = "1";

package/cli/src/devBack.mjs

@@ -52,6 +52,30 @@ export function stopDevBackContainers() {
   }
 }
 
+// Where the backend's 127.0.0.1 points. A local Muscat container (muscat-dev): join its
+// netns so the gateway and MediaMTX resolve like on the robot. Under `dev`: the bridge's
+// netns. Standalone dev:back: its own netns, gateway via the host.
+function backendNetwork(portRanges) {
+  const muscat = process.env.MUSCAT_PK_MUSCAT_CONTAINER;
+  if (muscat) return { run: ["--network", `container:${muscat}`], env: [], shared: true };
+  if (usesHostNetwork()) return { run: ["--network", "host"], env: [], shared: true };
+  const bridge = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
+  if (bridge) return { run: ["--network", `container:${bridge}`], env: [], shared: true };
+  return {
+    // host.docker.internal is automatic on Docker Desktop; this makes it resolve on Linux too.
+    run: [...publishPortFlags(portRanges), "--add-host", "host.docker.internal:host-gateway"],
+    env: ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"],
+    shared: false,
+  };
+}
+
+// Our own MediaMTX, only when `dev` found its ports free (a local Muscat brings its own).
+function startMediaServer(container) {
+  if (process.env.MUSCAT_PK_MEDIA !== "1") return;
+  spawnSync("docker", ["exec", "-d", container, "mediamtx", "/etc/mediamtx/mediamtx.yml"], { stdio: "ignore" });
+  log.step("MediaMTX: publish rtsp://127.0.0.1:8554/<path> · play http://localhost:8889/<path>");
+}
+
 // ── IDE tooling venv (best-effort, non-blocking) ────────────────────────────
 // `muscat-pk new` already creates this up front (see new.mjs); this just
 // refreshes it on every `dev`/`dev:back` in case requirements.txt changed.
@@ -95,39 +119,18 @@ async function runPython(root, portRanges) {
   // container shares the host's network stack, so it reaches the bridge at
   // localhost:10000 and the robot's Zenoh router / reverse-dial path directly
   // — no netns sharing, port publishing, host.docker.internal, or byte-proxy.
-  const useHostNet = usesHostNetwork();
-  // Share the bridge container's network namespace so localhost:10000 is the
-  // bridge (set by `muscat-pk dev`). Standalone dev:back has no bridge to join.
-  const bridgeContainer = process.env.MUSCAT_PK_BRIDGE_CONTAINER;
-  const netFlags = useHostNet
-    ? ["--network", "host"]
-    : bridgeContainer ? ["--network", `container:${bridgeContainer}`] : [];
+  const net = backendNetwork(portRanges);
   // Only the container's OWN reverse-dial path needs to publish a listen port.
-  // With host networking the port is already on the host; with the byte-proxy
+  // With a shared netns the port is already reachable; with the byte-proxy
   // the container just connects out — neither needs -p.
   const standaloneZenohPortFlags =
-    !useHostNet && !bridgeContainer && !proxyEndpoint && zenohPort
-      ? ["-p", `${zenohPort}:${zenohPort}`]
-      : [];
-  // Standalone dev:back owns its netns, so it publishes its own declared ports.
-  // Under `dev` the bridge owns the netns and published them already.
-  const pluginPortFlags =
-    !useHostNet && !bridgeContainer ? publishPortFlags(portRanges) : [];
-  const hostGatewayFlags = useHostNet || bridgeContainer
-    ? []
-    : ["--add-host", "host.docker.internal:host-gateway"];
-  // With host networking or the bridge's netns, 127.0.0.1:10000 (the SDK's
-  // gateway default) already reaches the bridge. Otherwise the container's own
-  // 127.0.0.1 is itself — host.docker.internal reaches the host.
-  const gatewayFlags = useHostNet || bridgeContainer
-    ? []
-    : ["-e", "RB_PLUGIN_GATEWAY_URL=http://host.docker.internal:10000"];
+    !net.shared && !proxyEndpoint && zenohPort ? ["-p", `${zenohPort}:${zenohPort}`] : [];
   const envFlags = [
     // docker exec below has no -t (no pseudo-TTY), so Python defaults to
     // block-buffered stdout — print() output wouldn't show up until the
     // buffer fills or the process exits. Force unbuffered.
     "-e", "PYTHONUNBUFFERED=1",
-    ...gatewayFlags,
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -147,15 +150,13 @@ async function runPython(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting Python dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...netFlags, ...standaloneZenohPortFlags, ...pluginPortFlags, ...realtimeFlags(),
-      // host.docker.internal is automatic on Docker Desktop (macOS/Windows);
-      // this makes it resolve on Linux too, for the no-bridge gateway fallback above.
-      ...hostGatewayFlags,
+    ["run", "-d", "--name", container, ...net.run, ...standaloneZenohPortFlags, ...realtimeFlags(),
       "-e", "PIP_ROOT_USER_ACTION=ignore",
       "-v", `${root}:/plugin`, "-w", "/plugin", PYTHON_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [zenohPort] });
 
   log.step("pip install requirements + watchfiles (in container)…");
@@ -373,7 +374,7 @@ runpy.run_path("/plugin/py/main.py", run_name="__main__")
 PY`]);
 
   if (pluginId) log.step(`RB_PLUGIN_ID=${pluginId}`);
-  if (useHostNet) log.step("network: host (native Linux — direct robot/bridge access)");
+  if (usesHostNetwork()) log.step("network: host (native Linux — direct robot/bridge access)");
   if (proxyEndpoint) log.step(`Zenoh via host byte-proxy → ${proxyEndpoint}`);
   else if (zenohAdvertiseHost && zenohPort) log.step(`Zenoh advertise → ${zenohAdvertiseHost}:${zenohPort}`);
   log.step("watchfiles → py/main.py (reload on any .py change in py/)");
@@ -429,10 +430,12 @@ async function runRos2(root, portRanges) {
   const container = `${ROS2_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges);
   const envFlags = [
     // Same rationale as runPython(): no -t on docker exec below means
     // rclpy's Python process stdout is block-buffered, not line-buffered.
     "-e", "PYTHONUNBUFFERED=1",
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -445,10 +448,11 @@ async function runRos2(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting ROS2 dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), "-e", "PIP_ROOT_USER_ACTION=ignore", "-v", `${root}:/plugin`, "-w", "/plugin", ROS2_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   // one-time deps + symlink build (edits to .py reflect without rebuilding)
@@ -459,11 +463,14 @@ async function runRos2(root, portRanges) {
   let child = null;
   const startNode = () => {
     if (child) child.kill();
-    log.step(`ros2 run ${pkg} ${pkg}_node`);
+    // Same command the robot runs: rclpy execs the console script, rclcpp uses `ros2 run`.
+    const launch = manifest.runtime?.launch || `${pkg}_node`;
+    const run = isRclcpp ? `ros2 run ${pkg} ${launch}` : `exec ${launch}`;
+    log.step(run);
     child = spawn(
       "docker",
       ["exec", ...envFlags, container, "bash", "-lc",
-        `cd ros2_ws && source install/setup.bash && ros2 run ${pkg} ${pkg}_node`],
+        `cd ros2_ws && source install/setup.bash && ${run}`],
       { cwd: root, stdio: "inherit" },
     );
   };
@@ -513,7 +520,9 @@ async function runCpp(root, portRanges) {
   const container = `${CPP_DEV_IMAGE}-run`;
   const robotIp    = process.env.MUSCAT_ROBOT_HOST  ?? "";
   const robotToken = process.env.MUSCAT_ROBOT_TOKEN ?? "";
+  const net = backendNetwork(portRanges);
   const envFlags = [
+    ...net.env,
     ...(pluginId    ? ["-e", `RB_PLUGIN_ID=${pluginId}`]             : []),
     ...(robotIp     ? ["-e", `MUSCAT_ROBOT_HOST=${robotIp}`]         : []),
     ...(robotToken  ? ["-e", `MUSCAT_ROBOT_TOKEN=${robotToken}`]     : []),
@@ -526,10 +535,11 @@ async function runCpp(root, portRanges) {
   docker(["rm", "-f", container], { stdio: "ignore" });
   log.step("starting C++ dev container…");
   const up = docker(
-    ["run", "-d", "--name", container, ...publishPortFlags(portRanges), ...realtimeFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
+    ["run", "-d", "--name", container, ...net.run, ...realtimeFlags(), "-v", `${root}:/plugin`, "-w", "/plugin", CPP_DEV_IMAGE, "sleep", "infinity"],
     { stdio: "inherit" },
   );
   if (up.status !== 0) throw new Error("failed to start dev container.");
+  startMediaServer(container);
   const stopPortMonitor = startPortContractMonitor({ container, ranges: portRanges, log, allow: [process.env.MUSCAT_ZENOH_PORT] });
 
   const build = () => {