Skip to content

Commit 2e86405

Browse files
committed
feat(policy): add declarative host mount schema, validation, and CLI (NVIDIA#1045)
- Add mounts: section to openclaw-sandbox.yaml policy schema - Add MountConfig type, validateMountPath, loadPolicyMounts in runner.ts - Refactor buildPlan() as single source of truth for plan construction - Add bin/lib/mounts.js for policy YAML mount management - Add mount-list and mount-add CLI commands to nemoclaw CLI - Emit warning when mounts declared but OpenShell lacks --volume support - Add test coverage for validation and YAML parsing - Runtime enforcement pending upstream NVIDIA/OpenShell#500
1 parent 3f923a4 commit 2e86405

7 files changed

Lines changed: 701 additions & 66 deletions

File tree

‎bin/lib/mounts.js‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
//
4+
// Mount management — read and write the mounts: section of the policy YAML.
5+
6+
const fs = require("fs");
7+
const path = require("path");
8+
const { ROOT } = require("./runner");
9+
10+
const POLICY_FILE = path.join(ROOT, "nemoclaw-blueprint", "policies", "openclaw-sandbox.yaml");
11+
12+
/**
13+
* @typedef {{ host_path: string; container_path: string; read_only?: boolean }} MountEntry
14+
*/
15+
16+
/**
17+
* Validate an absolute Unix path: must start with /, no null bytes, no .. components.
18+
* Returns the path unchanged on success; throws on failure.
19+
*/
20+
// Keep in sync with nemoclaw/src/blueprint/runner.ts:validateMountPath
21+
function validateMountPath(p, label) {
22+
if (!p || typeof p !== "string") throw new Error(`${label} is required`);
23+
if (!p.startsWith("/")) throw new Error(`${label} must be an absolute path: ${p}`);
24+
if (p.includes("\0")) throw new Error(`${label} must not contain null bytes`);
25+
if (p.split("/").some((s) => s === "..")) {
26+
throw new Error(`${label} must not contain path traversal: ${p}`);
27+
}
28+
return p;
29+
}
30+
31+
/**
32+
* Parse the mounts: section from raw policy YAML using a line-oriented state
33+
* machine. Returns an array of { host_path, container_path, read_only } objects.
34+
* Returns [] if the section is absent or empty.
35+
* @param {string} content
36+
* @returns {MountEntry[]}
37+
*/
38+
function parseMountsFromYaml(content) {
39+
/** @type {MountEntry[]} */
40+
const mounts = [];
41+
const lines = content.split("\n");
42+
let inMounts = false;
43+
/** @type {MountEntry | null} */
44+
let current = null;
45+
46+
for (const line of lines) {
47+
// Top-level mounts: key (possibly with inline empty list)
48+
if (/^mounts\s*:/.test(line)) {
49+
inMounts = true;
50+
// Inline empty: mounts: [] — nothing to collect
51+
continue;
52+
}
53+
54+
// Any non-indented, non-empty, non-comment line ends the section
55+
if (inMounts && line !== "" && /^\S/.test(line) && !line.startsWith("#")) {
56+
if (current) {
57+
mounts.push(current);
58+
current = null;
59+
}
60+
inMounts = false;
61+
continue;
62+
}
63+
64+
if (!inMounts) continue;
65+
66+
const trimmed = line.trim();
67+
if (!trimmed || trimmed.startsWith("#")) continue;
68+
69+
// New list item: " - host_path: ..."
70+
if (/^\s+-\s+\w/.test(line)) {
71+
if (current) mounts.push(current);
72+
current = /** @type {MountEntry} */ ({});
73+
parseKv(trimmed.replace(/^-\s+/, ""), current);
74+
continue;
75+
}
76+
77+
// Continuation key inside current item
78+
if (current && /^\s+\w/.test(line)) {
79+
parseKv(trimmed, current);
80+
}
81+
}
82+
83+
if (current) mounts.push(current);
84+
85+
return mounts.filter(
86+
(m) => typeof m.host_path === "string" && typeof m.container_path === "string",
87+
);
88+
}
89+
90+
function parseKv(line, obj) {
91+
const m = line.match(/^([\w]+)\s*:\s*(.*)$/);
92+
if (!m) return;
93+
const key = m[1];
94+
const raw = m[2].trim();
95+
if (raw === "true") obj[key] = true;
96+
else if (raw === "false") obj[key] = false;
97+
else obj[key] = raw;
98+
}
99+
100+
/**
101+
* Append a new mount entry to the mounts: section of the policy YAML in-place.
102+
* Returns true if written, false if the entry was already present.
103+
* Throws if the policy file does not exist.
104+
*/
105+
function addMountToPolicy(hostPath, containerPath, readOnly) {
106+
if (!fs.existsSync(POLICY_FILE)) {
107+
throw new Error(`Policy file not found: ${POLICY_FILE}`);
108+
}
109+
110+
const content = fs.readFileSync(POLICY_FILE, "utf-8");
111+
const existing = parseMountsFromYaml(content);
112+
113+
if (existing.some((m) => m.host_path === hostPath && m.container_path === containerPath)) {
114+
return false;
115+
}
116+
117+
const roLine = readOnly ? "\n read_only: true" : "";
118+
const newEntry = ` - host_path: ${hostPath}\n container_path: ${containerPath}${roLine}`;
119+
120+
const updated = insertMountEntry(content, newEntry);
121+
fs.writeFileSync(POLICY_FILE, updated, { encoding: "utf-8" });
122+
return true;
123+
}
124+
125+
/**
126+
* Insert a new mount entry into raw policy YAML content.
127+
* Handles: empty mounts: [], existing list, and missing section.
128+
*/
129+
function insertMountEntry(content, newEntry) {
130+
const lines = content.split("\n");
131+
let mountsIdx = -1;
132+
let sectionEndIdx = -1;
133+
134+
for (let i = 0; i < lines.length; i++) {
135+
if (/^mounts\s*:/.test(lines[i])) {
136+
mountsIdx = i;
137+
for (let j = i + 1; j < lines.length; j++) {
138+
const l = lines[j];
139+
if (l !== "" && /^\S/.test(l) && !l.startsWith("#")) {
140+
sectionEndIdx = j;
141+
break;
142+
}
143+
}
144+
break;
145+
}
146+
}
147+
148+
if (mountsIdx === -1) {
149+
// No mounts section — append at end
150+
return content.trimEnd() + "\n\nmounts:\n" + newEntry + "\n";
151+
}
152+
153+
const entryLines = newEntry.split("\n");
154+
155+
// Replace inline empty: mounts: []
156+
if (/^mounts\s*:\s*\[\s*\]/.test(lines[mountsIdx])) {
157+
lines[mountsIdx] = "mounts:";
158+
lines.splice(mountsIdx + 1, 0, ...entryLines);
159+
return lines.join("\n");
160+
}
161+
162+
// Insert before next top-level key, or at end of file
163+
const insertAt = sectionEndIdx === -1 ? lines.length : sectionEndIdx;
164+
lines.splice(insertAt, 0, ...entryLines);
165+
return lines.join("\n");
166+
}
167+
168+
/**
169+
* Load the mounts declared in the shared policy YAML.
170+
* Returns [] if the policy file is missing or the section is empty.
171+
* @returns {MountEntry[]}
172+
*/
173+
function loadMountsFromPolicy() {
174+
if (!fs.existsSync(POLICY_FILE)) return [];
175+
return parseMountsFromYaml(fs.readFileSync(POLICY_FILE, "utf-8"));
176+
}
177+
178+
module.exports = {
179+
POLICY_FILE,
180+
validateMountPath,
181+
parseMountsFromYaml,
182+
insertMountEntry,
183+
loadMountsFromPolicy,
184+
addMountToPolicy,
185+
};

‎bin/nemoclaw.js‎

Lines changed: 74 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ const {
3030
shellQuote,
3131
validateName,
3232
} = require("./lib/runner");
33+
const mounts = require("./lib/mounts");
3334
const { resolveOpenshell } = require("./lib/resolve-openshell");
3435
const { startGatewayForRecovery } = require("./lib/onboard");
3536
const {
@@ -1088,6 +1089,66 @@ function sandboxPolicyList(sandboxName) {
10881089
console.log("");
10891090
}
10901091

1092+
function sandboxMountList(sandboxName) {
1093+
const list = mounts.loadMountsFromPolicy();
1094+
1095+
console.log("");
1096+
console.log(` Mounts for sandbox '${sandboxName}':`);
1097+
if (list.length === 0) {
1098+
console.log(" (none configured)");
1099+
console.log("");
1100+
console.log(
1101+
` To add a mount: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`,
1102+
);
1103+
} else {
1104+
for (const m of list) {
1105+
const ro = m.read_only ? " [read-only]" : "";
1106+
console.log(` ${m.host_path} → ${m.container_path}${ro}`);
1107+
}
1108+
console.log("");
1109+
console.log(" Note: mounts take effect on the next sandbox creation.");
1110+
console.log(
1111+
` To add more: nemoclaw ${sandboxName} mount-add <host-path> <container-path> [--read-only]`,
1112+
);
1113+
}
1114+
console.log("");
1115+
}
1116+
1117+
function sandboxMountAdd(sandboxName, args) {
1118+
const hostPath = args[0];
1119+
const containerPath = args[1];
1120+
const readOnly = args.includes("--read-only");
1121+
1122+
if (!hostPath || !containerPath) {
1123+
console.error(" Usage: nemoclaw <name> mount-add <host-path> <container-path> [--read-only]");
1124+
console.error("");
1125+
console.error(" Examples:");
1126+
console.error(" nemoclaw openclaw mount-add /home/user/datasets /data/datasets --read-only");
1127+
console.error(" nemoclaw openclaw mount-add /home/user/projects /workspace/projects");
1128+
process.exit(1);
1129+
}
1130+
1131+
try {
1132+
mounts.validateMountPath(hostPath, "host-path");
1133+
mounts.validateMountPath(containerPath, "container-path");
1134+
} catch (err) {
1135+
console.error(` ${err.message}`);
1136+
process.exit(1);
1137+
}
1138+
1139+
const added = mounts.addMountToPolicy(hostPath, containerPath, readOnly);
1140+
if (!added) {
1141+
console.log(` Mount already configured: ${hostPath} → ${containerPath}`);
1142+
return;
1143+
}
1144+
1145+
const roNote = readOnly ? " (read-only)" : "";
1146+
console.log(` ${G}✓${R} Added mount${roNote}: ${hostPath} → ${containerPath}`);
1147+
console.log(" This mount will take effect on the next sandbox creation.");
1148+
console.log(` Note: --volume support is pending (NVIDIA/OpenShell#500). The mount is`);
1149+
console.log(` recorded in the policy now so it takes effect automatically once supported.`);
1150+
}
1151+
10911152
async function sandboxDestroy(sandboxName, args = []) {
10921153
const skipConfirm = args.includes("--yes") || args.includes("--force");
10931154
if (!skipConfirm) {
@@ -1143,6 +1204,10 @@ function help() {
11431204
nemoclaw <name> policy-add Add a network or filesystem policy preset
11441205
nemoclaw <name> policy-list List presets ${D}(● = applied)${R}
11451206
1207+
${G}Host Mounts:${R}
1208+
nemoclaw <name> mount-list List host→sandbox bind mounts
1209+
nemoclaw <name> mount-add Add a bind mount ${D}(--read-only optional)${R}
1210+
11461211
${G}Deploy:${R}
11471212
nemoclaw deploy <instance> Deploy to a Brev VM and start services
11481213
@@ -1249,12 +1314,20 @@ const [cmd, ...args] = process.argv.slice(2);
12491314
case "policy-list":
12501315
sandboxPolicyList(cmd);
12511316
break;
1317+
case "mount-list":
1318+
sandboxMountList(cmd);
1319+
break;
1320+
case "mount-add":
1321+
await sandboxMountAdd(cmd, actionArgs);
1322+
break;
12521323
case "destroy":
12531324
await sandboxDestroy(cmd, actionArgs);
12541325
break;
12551326
default:
12561327
console.error(` Unknown action: ${action}`);
1257-
console.error(` Valid actions: connect, status, logs, policy-add, policy-list, destroy`);
1328+
console.error(
1329+
` Valid actions: connect, status, logs, policy-add, policy-list, mount-list, mount-add, destroy`,
1330+
);
12581331
process.exit(1);
12591332
}
12601333
return;

‎nemoclaw-blueprint/policies/openclaw-sandbox.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,22 @@ filesystem_policy:
3636
- /dev/null
3737
- /sandbox/.openclaw-data # Writable agent/plugin state (symlinked from .openclaw)
3838

39+
# Host filesystem mounts — bind-mounted into the sandbox at creation time.
40+
# Each entry is translated into a Docker --volume flag (host_path:container_path[:ro]).
41+
# Mount paths must be absolute. Container paths must also appear in
42+
# filesystem_policy.read_write (or read_only) for Landlock to permit access.
43+
# Static mounts are applied once at sandbox creation and cannot be hot-added.
44+
#
45+
# Example:
46+
# mounts:
47+
# - host_path: /home/user/datasets
48+
# container_path: /data/datasets
49+
# read_only: true
50+
# - host_path: /home/user/projects
51+
# container_path: /workspace/projects
52+
53+
mounts: []
54+
3955
landlock:
4056
compatibility: best_effort
4157

0 commit comments

Comments
 (0)