feat(vm): support shared folder mounts

[hasnatelias]

Summary

Adds shared host-folder support for libkrun-based VM sandboxes using virtiofs. Operators can expose host directories inside a VM with live, bidirectional updates through VM-specific driver configuration.

Related Issue

WIP #2585

Changes

• Add VM mounts configuration compatible with Docker and Podman bind-mount entries.
• Add the enable_bind_mounts operator-controlled safety gate.
• Validate host sources, guest targets, duplicate and overlapping mounts, reserved paths, and unsupported QEMU configurations.
• Export validated host directories through libkrun using krun_add_virtiofs4.
• Generate stable virtiofs tags and inject a driver-owned mount manifest into the guest overlay.
• Mount virtiofs shares during guest initialization before starting the sandbox workload.
• Support multiple read-only and read-write directory mounts.
• Preserve existing behavior when no mounts are configured.
• Enable FUSE and virtiofs support in the VM guest kernel configuration.
• Add unit and VM E2E coverage.
• Document VM shared-folder configuration and operational constraints.

Architecture

flowchart LR
    subgraph Host["Host / Gateway Machine"]
        HD["Host directory<br/><code>/host/project</code>"]
        CFG["Sandbox configuration<br/><code>driver_config.vm.mounts[]</code>"]
        DRV["OpenShell VM driver<br/>Validate paths and assign<br/><code>osfs&lt;N&gt;</code> tags"]
        KRUN["libkrun<br/><code>krun_add_virtiofs4(...)</code>"]

        HD --> CFG
        CFG --> DRV
        DRV --> KRUN
    end

    subgraph Guest["VM Sandbox"]
        BOOT["VM boot<br/>Read driver-owned<br/>mount manifest"]
        MOUNT["Guest initialization<br/><code>mount -t virtiofs</code>"]
        TARGET["Shared guest directory<br/><code>/sandbox/project</code>"]
        WORKLOAD["Sandbox workload"]
        
        BOOT --> MOUNT
        MOUNT --> TARGET
        TARGET --> WORKLOAD
    end

    KRUN -->|"virtiofs export"| BOOT
    TARGET -. "guest writes propagate to host" .-> HD
    HD -. "host writes appear in guest" .-> TARGET

Loading

Example:

{
  "vm": {
    "mounts": [
      {
        "type": "bind",
        "source": "/host/project",
        "target": "/sandbox/project",
        "read_only": false
      }
    ]
  }
}

The gateway administrator must explicitly enable caller-provided configuration and VM bind mounts:

[openshell.drivers.vm]
allow_driver_config = true
enable_bind_mounts = true

[openshell.drivers.vm.resource_admission]
enabled = false

Testing

Current verification performed:

• git diff --check — passed.

• VM guest-init shell syntax check with bash -n — passed.

• VM E2E runner shell syntax check with bash -n — passed.

• Added unit coverage for parsing, read-only defaults, multiple mounts, invalid sources and targets, duplicate and overlapping targets, reserved paths, QEMU rejection, manifest generation, and launch-argument parsing.

• Added a VM E2E test covering host-to-guest visibility, guest-to-host writes, and read-only enforcement.

• Rust formatting and tests were not executed locally because cargo and mise were unavailable.

• The VM E2E test was not executed locally because it requires a supported macOS/HVF or Linux/KVM host with libkrun.

• Checks appropriate to the affected code and behavior pass

• Unit tests added/updated

• E2E tests added/updated

Checklist

• Follows [Conventional Commits](https://www.conventionalcommits.org/)
• Commits are signed off (DCO)
• Architecture docs updated

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

Thank you for your interest in contributing to OpenShell, @hasnatelias.

This project uses a vouch system for first-time contributors. Before submitting a pull request, you need to be vouched by a maintainer.

To get vouched:

1. Open a Vouch Request discussion.
2. Describe what you want to change and why.
3. Write in your own words — do not have an AI generate the request.
4. A maintainer will comment /vouch if approved.
5. Once vouched, open a new PR (preferred) or reopen this one after a few minutes.

See CONTRIBUTING.md for details.

[github-actions]

Thank you for your submission! We ask that you sign our Developer Certificate of Origin before we can accept your contribution. You can sign the DCO by adding a comment below using this text:

---

I have read the DCO document and I hereby sign the DCO.

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the DCO Assistant Lite bot.}