Declarative Interface for Host Filesystem Access and Volume Mounting (WSL/Local Dev)

Problem Statement

Currently, NemoClaw's sandbox permissions are highly secure by design, utilizing Landlock and OpenShell to isolate the agent. However, this strict isolation becomes a significant friction point for local development workflows.

When running NemoClaw (e.g., via WSL 2 on Windows), users cannot easily grant the agent access to existing project directories located on the host machine (such as /mnt/c/Users/path/to/project ). Without the ability to securely read/write to external local directories, the agent cannot easily act as a local co-pilot, analyze existing local logs, or generate code directly into a developer's active workspace.

Proposed Design

How should this work?
We need a declarative way to safely bind-mount host directories into the sandbox while dynamically updating the internal security policies to permit access.

System Behavior & Components Involved:

CLI Interface: Introduce a new flag to the existing sandbox management commands, or a specific policy command. For example: nemoclaw sandbox policy-add --mount /host/local/path:/sandbox/target/path .

Container Level (Docker): When the sandbox is started or updated, the NemoClaw orchestrator translates this configuration into a standard Docker bind mount (-v /host/local/path:/sandbox/target/path).

Security Level (OpenShell & Landlock): The OpenShell gateway must dynamically read these custom mount paths from the configuration and append them to the Landlock whitelist during the sandbox initialization. This ensures the agent can read/write to the mounted directory without triggering kernel-level Permission denied errors.

User-Facing Interface:
Users should be able to define these mounts either interactively during nemoclaw onboard or declaratively via the CLI (e.g., nemoclaw sandbox mount add <local_path> ).

Alternatives Considered

1. Manually copying files via docker cp

Why it was evaluated: Users can theoretically copy their project files into the sandbox's default volume, let the agent modify them, and copy them back out.

Why the proposed design is better: It completely breaks the seamless local development loop. Changes made by the agent aren't immediately reflected in the user's host IDE, leading to data duplication and sync headaches.

2. Disabling Landlock / OpenShell

Why it was evaluated: Running the agent with elevated privileges or --privileged docker flags to bypass restrictions.

Why the proposed design is better: It defeats the core value proposition of NemoClaw (secure, guardrailed AI execution). The proposed design maintains the secure sandbox while opening specifically allowed, trackable "wormholes" to the host.

Checklist

I searched existing issues and this is not a duplicate
This is a design proposal, not a "please build this" request

Thanks a lot!

@ctongh

Great design proposal @ctongh — the gap between strict sandbox isolation and local dev usability is real, and this is a clean way to address it without compromising NemoClaw's security model.

I'd like to take this on. Here's my proposed implementation plan:

Implementation Approach

1. Policy Schema Extension (`nemoclaw-blueprint/policies/`)

Add a mounts: section to the existing openclaw-sandbox.yaml schema, following the same declarative YAML pattern used for network: and filesystem: policies today:

mounts:
  - name: "project-workspace"
    host_path: "/mnt/c/Users/dev/my-project"
    sandbox_path: "/sandbox/workspace"
    mode: "rw"           # rw | ro
    allowed_binaries:     # restrict which processes can access
      - openclaw
      - git
      - node

The allowed_binaries field follows the same pattern as network policy binaries restrictions (ref: the pattern in openclaw-sandbox.yaml network entries) — ensuring that even within the mounted path, only explicitly approved processes can read/write. This prevents a rogue subprocess from touching mounted host files even if the mount exists.

2. Blueprint Runner Changes (`nemoclaw-blueprint/orchestrator/runner.py`)

In the apply phase:

Parse mounts: entries from the policy YAML
Translate each entry into Docker -v bind mount flags during openshell sandbox create
Pass the sandbox_path targets to OpenShell for Landlock whitelist inclusion
Validate that host_path exists and is accessible before sandbox creation (fail early with a clear error rather than a cryptic Landlock denial)

3. CLI Commands (`nemoclaw/src/commands/`)

New mount.ts command with subcommands:

nemoclaw <sandbox-name> mount add /host/path:/sandbox/path [--mode rw|ro]
nemoclaw <sandbox-name> mount list
nemoclaw <sandbox-name> mount remove /sandbox/path

add writes to the policy YAML and calls openshell policy set for dynamic application (session-scoped), or prompts the user to re-onboard for persistence
list reads the active mount configuration from sandbox state
remove unmounts and updates policy

Register in index.ts and wire through cli.ts following the existing command pattern (launch, connect, status, logs).

4. Onboard Integration (`bin/lib/onboard.js`)

Add an optional step during nemoclaw onboard:

Mount a local project directory? [y/N]: y
Host path: /mnt/c/Users/dev/my-project
Sandbox path [/sandbox/workspace]: 
Access mode [rw/ro]: rw

This gets written into the static policy so it persists across restarts.

5. Security Guardrails

A few things I'd build in to keep this safe:

No parent traversal: Reject host_path containing .. or symlinks that resolve outside the declared path
Deny sensitive paths: Hardcoded blocklist for ~/.ssh, ~/.aws, ~/.gnupg, browser profile dirs — even if the user explicitly tries to mount them. These are the exact paths Landlock is designed to protect; punching holes for them defeats the purpose
Audit logging: Every mount operation (add/remove) gets logged with timestamp and user confirmation, visible via nemoclaw <name> status
WSL path normalization: Auto-detect WSL environment and handle /mnt/c/ --> C:\ path translation transparently

Scope & Phasing

I'd suggest shipping this in two phases:

Phase 1: Static mounts via openclaw-sandbox.yaml + onboard prompt (requires sandbox recreation)
Phase 2: Dynamic nemoclaw mount add/remove on running sandboxes (depends on OpenShell supporting live Landlock updates)

Phase 1 covers the primary use case (local dev setup) and doesn't require any OpenShell changes. Phase 2 can follow once the upstream support is available.

Happy to start on Phase 1. I'll open a draft PR once I have the schema extension and runner changes working against the current main branch. Let me know if the maintainers have any concerns with the approach or if there are any OpenShell constraints I should account for.

@AddyM

Hi @AddyM , thanks for the lightning-fast response! I really appreciate you taking this on.

I also completely agree with your scoping. Phase 1 (static mounts via openclaw-sandbox.yaml and the onboard prompt) already solves 90% of the friction for daily local development workflows. Phase 2 can definitely wait until OpenShell supports live updates.

Since I have a dedicated Windows 11 / WSL 2 environment set up right now, I'd be more than happy to help test any experimental branches or PRs you push out. Just ping me here whenever you need someone to verify the bind mounts and Landlock policy behaviors on a WSL setup!

@ctongh

Thanks @ctongh! Starting on Phase 1 now — static mounts via the policy YAML + onboard integration. I'll tag you on the draft PR once I have the schema extension and runner changes working. Your WSL 2 testing will be especially valuable for path normalization (/mnt/c/ handling).

@AddyM

Hi @AddyM Thanks for doing this. I was trying to do something similar and have a question on the proposed design

Translate each entry into Docker -v bind mount flags during openshell sandbox create

I checked openshell and didn't find an option which allows mounting using -v. The request for this enhancement has been closed as not planned NVIDIA/OpenShell#500
So am I missing something? or your plan is to add the -v feature to openshell as well?

@ninja18

Good catch @ninja18 — I confirmed NVIDIA/OpenShell#500 was closed as not planned, so --volume isn't available on openshell sandbox create.

Adjusting the approach: The NemoClaw-side contract (policy schema, validation, CLI commands, buildPlan() integration) is already implemented and stands on its own. The actionApply path will emit a clear warning when mounts are declared but OpenShell lacks volume support, rather than silently failing.

I plan to open a narrowly scoped proposal on OpenShell for a minimal --volume host:container[:ro] bind mount flag — no PVCs, just local dev mounts. This PR becomes the first consumer when that lands.
Shipping the interface ahead of the runtime is intentional — it lets us converge on schema and CLI UX now, so there's no second design cycle when OpenShell adds the capability.

@ctongh — no change to the WSL 2 testing plan. I'll tag you on the draft PR and keep you posted on the upstream proposal.

feat(policy): add declarative host mount schema, validation, and CLI (N…

@ctongh

Since I have a dedicated Windows 11 / WSL 2 environment set up right now, I'd be more than happy to help test any experimental branches or PRs you push out

Hello @ctongh , I have raised a PR sometime back , would you like to validate it?

Thank you folks for working on this, just now getting to the point that nemoclaw feels usable on windows as well as safe. If you need another tester then prod me as I'm keen to get the file sharing flow easier from Windows Explorer + Apps (IDEs/shells) / WSL.

@ctongh

Hi @ctongh, thanks for the report. This one has been open a while: 67 releases have shipped since it was filed (we are now on v0.0.67), with onboarding, the sandbox runtime, config generation, and many platform paths reworked along the way. Could you check whether this is still something you need on the latest version? Cheers!

@latenighthackathon

Hi @latenighthackathon , since this issue has shift from many versions, I think it would be more appropriate to resubmit it in the future if there is still demand for it. This issue can be closed. Thank you!

@ctongh

Thanks @ctongh! @wscurran - closing this issue, cheers!

Status clarification: #1045 was closed at the reporter's request after the original NemoClaw implementation in #1189 closed without merging. #2773 added bidirectional SSHFS sharing from the sandbox to the host, but it does not provide the requested read-only host-to-sandbox bind mount.

OpenShell later added gated Docker and Podman bind mounts through --driver-config-json in NVIDIA/OpenShell#1785, with read-only access as the default; NVIDIA/OpenShell#2092 added SELinux label support. NemoClaw does not yet expose that capability during onboarding, so a current follow-up issue will track the remaining NemoClaw CLI and lifecycle integration.

Follow-up implementation is now tracked in #8274 and PR #8280. The PR adds repeatable, read-only host directory mounts for Linux/WSL2 onboarding, with validation, lifecycle persistence, status reporting, and documentation.

Navigation Menu

Repository navigation

Declarative Interface for Host Filesystem Access and Volume Mounting (WSL/Local Dev) #1045

Problem Statement

Proposed Design

Alternatives Considered

Category

Checklist

Implementation Approach

1. Policy Schema Extension (`nemoclaw-blueprint/policies/`)

2. Blueprint Runner Changes (`nemoclaw-blueprint/orchestrator/runner.py`)

3. CLI Commands (`nemoclaw/src/commands/`)

4. Onboard Integration (`bin/lib/onboard.js`)

5. Security Guardrails

Scope & Phasing

4 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Declarative Interface for Host Filesystem Access and Volume Mounting (WSL/Local Dev) #1045

Description

Problem Statement

Proposed Design

Alternatives Considered

Category

Checklist

Activity

AddyM commented on Mar 29, 2026

Implementation Approach

1. Policy Schema Extension (nemoclaw-blueprint/policies/)

2. Blueprint Runner Changes (nemoclaw-blueprint/orchestrator/runner.py)

3. CLI Commands (nemoclaw/src/commands/)

4. Onboard Integration (bin/lib/onboard.js)

5. Security Guardrails

Scope & Phasing

ctongh commented on Mar 29, 2026

AddyM commented on Mar 30, 2026

ninja18 commented on Mar 31, 2026

AddyM commented on Mar 31, 2026

AddyM commented on Apr 10, 2026

4 remaining items

tyeth commented on Jun 12, 2026

latenighthackathon commented on Jun 24, 2026

ctongh commented on Jun 24, 2026

latenighthackathon commented on Jun 24, 2026

ericksoa commented on Aug 5, 2026

ericksoa commented on Aug 5, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

1. Policy Schema Extension (`nemoclaw-blueprint/policies/`)

2. Blueprint Runner Changes (`nemoclaw-blueprint/orchestrator/runner.py`)

3. CLI Commands (`nemoclaw/src/commands/`)

4. Onboard Integration (`bin/lib/onboard.js`)