feat(policy): declarative host mount schema, validation, and CLI (#1045)

bin/lib/mounts.js

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Mount management — read and write the mounts: section of the policy YAML.
+
+const fs = require("fs");
+const path = require("path");
+const { ROOT } = require("./runner");
+
+const POLICY_FILE = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
+
+/**
+ * @typedef {{ host_path: string; container_path: string; read_only?: boolean }} MountEntry
+ */
+
+/**
+ * Validate an absolute Unix path: must start with /, no null bytes, no .. components.
+ * Returns the path unchanged on success; throws on failure.
+ */
+// Keep in sync with nemoclaw/src/blueprint/runner.ts:validateMountPath
+function validateMountPath(p, label) {
+  if (!p || typeof p !== "string") throw new Error(`${label} is required`);
+  if (!p.startsWith("/")) throw new Error(`${label} must be an absolute path: ${p}`);
+  if (p.includes("\0")) throw new Error(`${label} must not contain null bytes`);
+  if (p.split("/").some((s) => s === "..")) {
+    throw new Error(`${label} must not contain path traversal: ${p}`);
+  }
+  return p;
+}
+
+/**
+ * Parse the mounts: section from raw policy YAML using a line-oriented state
+ * machine. Returns an array of { host_path, container_path, read_only } objects.
+ * Returns [] if the section is absent or empty.
+ * @param {string} content
+ * @returns {MountEntry[]}
+ */
+function parseMountsFromYaml(content) {
+  /** @type {MountEntry[]} */
+  const mounts = [];
+  const lines = content.split("\n");
+  let inMounts = false;
+  /** @type {MountEntry | null} */
+  let current = null;
+
+  for (const line of lines) {
+    // Top-level mounts: key (possibly with inline empty list)
+    if (/^mounts\s*:/.test(line)) {
+      inMounts = true;
+      // Inline empty: mounts: [] — nothing to collect
+      continue;
+    }
+
+    // Any non-indented, non-empty, non-comment line ends the section
+    if (inMounts && line !== "" && /^\S/.test(line) && !line.startsWith("#")) {
+      if (current) {
+        mounts.push(current);
+        current = null;
+      }
+      inMounts = false;
+      continue;
+    }
+
+    if (!inMounts) continue;
+
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    // New list item: "  - host_path: ..."
+    if (/^\s+-\s+\w/.test(line)) {
+      if (current) mounts.push(current);
+      current = /** @type {MountEntry} */ ({});
+      parseKv(trimmed.replace(/^-\s+/, ""), current);
+      continue;
+    }
+
+    // Continuation key inside current item
+    if (current && /^\s+\w/.test(line)) {
+      parseKv(trimmed, current);
+    }
+  }
+
+  if (current) mounts.push(current);
+
+  return mounts.filter(
+    (m) => typeof m.host_path === "string" && typeof m.container_path === "string",
+  );
+}
+
+function parseKv(line, obj) {
+  const m = line.match(/^([\w]+)\s*:\s*(.*)$/);
+  if (!m) return;
+  const key = m[1];
+  const raw = m[2].trim();
+  if (raw === "true") obj[key] = true;
+  else if (raw === "false") obj[key] = false;
+  else obj[key] = raw;
+}
+
+/**
+ * Append a new mount entry to the mounts: section of the policy YAML in-place.
+ * Returns true if written, false if the entry was already present.
+ * Throws if the policy file does not exist.
+ */
+function addMountToPolicy(hostPath, containerPath, readOnly) {
+  if (!fs.existsSync(POLICY_FILE)) {
+    throw new Error(`Policy file not found: ${POLICY_FILE}`);
+  }
+
+  const content = fs.readFileSync(POLICY_FILE, "utf-8");
+  const existing = parseMountsFromYaml(content);
+
+  if (existing.some((m) => m.host_path === hostPath && m.container_path === containerPath)) {
+    return false;
+  }
+
+  const roLine = readOnly ? "\n    read_only: true" : "";
+  const newEntry = `  - host_path: ${hostPath}\n    container_path: ${containerPath}${roLine}`;
+
+  const updated = insertMountEntry(content, newEntry);
+  fs.writeFileSync(POLICY_FILE, updated, { encoding: "utf-8" });
+  return true;
+}
+
+/**
+ * Insert a new mount entry into raw policy YAML content.
+ * Handles: empty mounts: [], existing list, and missing section.
+ */
+function insertMountEntry(content, newEntry) {
+  const lines = content.split("\n");
+  let mountsIdx = -1;
+  let sectionEndIdx = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    if (/^mounts\s*:/.test(lines[i])) {
+      mountsIdx = i;
+      for (let j = i + 1; j < lines.length; j++) {
+        const l = lines[j];
+        if (l !== "" && /^\S/.test(l) && !l.startsWith("#")) {
+          sectionEndIdx = j;
+          break;
+        }
+      }
+      break;
+    }
+  }
+
+  if (mountsIdx === -1) {
+    // No mounts section — append at end
+    return content.trimEnd() + "\n\nmounts:\n" + newEntry + "\n";
+  }
+
+  const entryLines = newEntry.split("\n");
+
+  // Replace inline empty: mounts: []
+  if (/^mounts\s*:\s*\[\s*\]/.test(lines[mountsIdx])) {
+    lines[mountsIdx] = "mounts:";
+    lines.splice(mountsIdx + 1, 0, ...entryLines);
+    return lines.join("\n");
+  }
+
+  // Insert before next top-level key, or at end of file
+  const insertAt = sectionEndIdx === -1 ? lines.length : sectionEndIdx;
+  lines.splice(insertAt, 0, ...entryLines);
+  return lines.join("\n");
+}
+
+/**
+ * Load the mounts declared in the shared policy YAML.
+ * Returns [] if the policy file is missing or the section is empty.
+ * @returns {MountEntry[]}
+ */
+function loadMountsFromPolicy() {
+  if (!fs.existsSync(POLICY_FILE)) return [];
+  return parseMountsFromYaml(fs.readFileSync(POLICY_FILE, "utf-8"));
+}
+
+module.exports = {
+  POLICY_FILE,
+  validateMountPath,
+  parseMountsFromYaml,
+  insertMountEntry,
+  loadMountsFromPolicy,
+  addMountToPolicy,
+};

bin/nemoclaw.js

@@ -30,6 +30,7 @@ const {
   shellQuote,
   validateName,
 } = require("./lib/runner");
+const mounts = require("./lib/mounts");
 const { resolveOpenshell } = require("./lib/resolve-openshell");
 const { startGatewayForRecovery } = require("./lib/onboard");
 const {
@@ -1088,6 +1089,66 @@ function sandboxPolicyList(sandboxName) {
   console.log("");
 }
 
+function sandboxMountList(sandboxName) {
+  const list = mounts.loadMountsFromPolicy();
+
+  console.log("");
+  console.log(`  Mounts for sandbox '${sandboxName}':`);
+  if (list.length === 0) {
+    console.log("    (none configured)");
+    console.log("");
+    console.log(
+      `  To add a mount: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`,
+    );
+  } else {
+    for (const m of list) {
+      const ro = m.read_only ? "  [read-only]" : "";
+      console.log(`    ${m.host_path}  →  ${m.container_path}${ro}`);
+    }
+    console.log("");
+    console.log("  Note: mounts take effect on the next sandbox creation.");
+    console.log(
+      `  To add more: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`,
+    );
+  }
+  console.log("");
+}
+
+function sandboxMountAdd(sandboxName, args) {
+  const hostPath = args[0];
+  const containerPath = args[1];
+  const readOnly = args.includes("--read-only");
+
+  if (!hostPath || !containerPath) {
+    console.error("  Usage: nemoclaw <name> mount-add <host-path> <container-path> [--read-only]");
+    console.error("");
+    console.error("  Examples:");
+    console.error("    nemoclaw openclaw mount-add /home/user/datasets /data/datasets --read-only");
+    console.error("    nemoclaw openclaw mount-add /home/user/projects /workspace/projects");
+    process.exit(1);
+  }
+
+  try {
+    mounts.validateMountPath(hostPath, "host-path");
+    mounts.validateMountPath(containerPath, "container-path");
+  } catch (err) {
+    console.error(`  ${err.message}`);
+    process.exit(1);
+  }
+
+  const added = mounts.addMountToPolicy(hostPath, containerPath, readOnly);
+  if (!added) {
+    console.log(`  Mount already configured: ${hostPath} → ${containerPath}`);
+    return;
+  }
+
+  const roNote = readOnly ? " (read-only)" : "";
+  console.log(`  ${G}✓${R} Added mount${roNote}: ${hostPath} → ${containerPath}`);
+  console.log("  This mount will take effect on the next sandbox creation.");
+  console.log(`  Note: --volume support is pending (NVIDIA/OpenShell#500). The mount is`);
+  console.log(`  recorded in the policy now so it takes effect automatically once supported.`);
+}
+
 async function sandboxDestroy(sandboxName, args = []) {
   const skipConfirm = args.includes("--yes") || args.includes("--force");
   if (!skipConfirm) {
@@ -1143,6 +1204,10 @@ function help() {
     nemoclaw <name> policy-add       Add a network or filesystem policy preset
     nemoclaw <name> policy-list      List presets ${D}(● = applied)${R}
 
+  ${G}Host Mounts:${R}
+    nemoclaw <name> mount-list       List host→sandbox bind mounts
+    nemoclaw <name> mount-add        Add a bind mount ${D}(--read-only optional)${R}
+
   ${G}Deploy:${R}
     nemoclaw deploy <instance>       Deploy to a Brev VM and start services
 
@@ -1249,12 +1314,20 @@ const [cmd, ...args] = process.argv.slice(2);
       case "policy-list":
         sandboxPolicyList(cmd);
         break;
+      case "mount-list":
+        sandboxMountList(cmd);
+        break;
+      case "mount-add":
+        await sandboxMountAdd(cmd, actionArgs);
+        break;
       case "destroy":
         await sandboxDestroy(cmd, actionArgs);
         break;
       default:
         console.error(`  Unknown action: ${action}`);
-        console.error(`  Valid actions: connect, status, logs, policy-add, policy-list, destroy`);
+        console.error(
+          `  Valid actions: connect, status, logs, policy-add, policy-list, mount-list, mount-add, destroy`,
+        );
         process.exit(1);
     }
     return;

nemoclaw-blueprint/policies/openclaw-sandbox.yaml

@@ -36,6 +36,22 @@ filesystem_policy:
     - /dev/null
     - /sandbox/.openclaw-data       # Writable agent/plugin state (symlinked from .openclaw)
 
+# Host filesystem mounts — bind-mounted into the sandbox at creation time.
+# Each entry is translated into a Docker --volume flag (host_path:container_path[:ro]).
+# Mount paths must be absolute. Container paths must also appear in
+# filesystem_policy.read_write (or read_only) for Landlock to permit access.
+# Static mounts are applied once at sandbox creation and cannot be hot-added.
+#
+# Example:
+#   mounts:
+#     - host_path: /home/user/datasets
+#       container_path: /data/datasets
+#       read_only: true
+#     - host_path: /home/user/projects
+#       container_path: /workspace/projects
+
+mounts: []
+
 landlock:
   compatibility: best_effort