Skip to content

feat(vm): configure the sandbox workspace root - #5797

Open
shiju-nv wants to merge 2 commits into
mainfrom
feat/5282-vm-workspace-root/shiju-nv
Open

shiju-nv wants to merge 2 commits into
mainfrom
feat/5282-vm-workspace-root/shiju-nv

Conversation

@shiju-nv

@shiju-nv shiju-nv commented Nov 20, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Make the MicroVM workspace configurable so images built around paths such as /home/agent can run without changing the VM driver. Keep /sandbox as the default, and support either an operator-managed directory or the image's OCI WORKDIR.

Related Issue

Closes #5282

Changes

  • Add workspace_mode (managed or image) and workspace_root to VM gateway configuration, with matching VM driver flags.
  • Prepare custom managed directories for the sandbox user, preserving ownership of existing contents and updating the sandbox account's home. Require custom image workspaces to exist without symlink components and be writable by the resolved sandbox user.
  • Persist the selected workspace and retain the prepared workload image across restarts. Existing VMs without workspace metadata keep /sandbox.
  • Share reserved-path validation between the gateway and driver, and validate bind mounts against the selected workspace.
  • Add coverage for workspace selection, persistence, reserved paths, mount conflicts, and image workdir resolution from the pinned registry image. Update the VM README and gateway/runtime documentation.

Release Notes

Configure [openshell.drivers.vm] with workspace_mode = "managed" and workspace_root = "/home/agent" to choose a workspace, or use workspace_mode = "image" to follow the image's OCI WORKDIR. Missing, empty, /, and /sandbox workdirs, including rootfs tar archives without OCI metadata, fall back to managed /sandbox. The selected workspace is fixed when the sandbox is created.

Testing

  • Checks appropriate to the affected code and behavior pass
  • Unit tests added/updated (if applicable)
  • E2E tests added/updated (if applicable)

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

Signed-off-by: Shiju <shiju@nvidia.com>
@github-actions github-actions Bot added the state:accepted A maintainer decided OpenShell should pursue this issue label Nov 20, 2026
@github-actions

Copy link
Copy Markdown

Signed-off-by: Shiju <shiju@nvidia.com>
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. rust-sdk — No explicit risk acceptance found

raw::proto::ProviderCredentialRefreshStrategy gains GithubAppInstallation, extending an existing exhaustive Rust enum.

  • Impact: SDK consumers matching all previous variants without a wildcard fail to compile, while ordinary RPC client calls remain unaffected.
  • Action: Preserve the baseline generated enum for v0.1.10, or defer its extension to a minor release with notice and wildcard-match migration guidance.
  • PR: feat(vm): configure the sandbox workspace root #5797

2. cli — No explicit risk acceptance found

openshell-gateway mutation audit status_detail changes from rejected:&lt;code&gt; or error:&lt;code&gt; to optionally include a third :&lt;reason&gt; component.

  • Impact: Existing JSONL and stderr audit consumers using the documented two-component format can reject records or stop matching failure alerts.
  • Action: Keep the existing two-component status_detail format for v0.1.10 and expose the reason separately, or defer the format change to a minor release with parser migration guidance.
  • PR: feat(vm): configure the sandbox workspace root #5797
Review details
  • Execution: complete
  • Candidate: PR #5797 (3bc117380b03200c8ec5105cd0c9686a02ce18c5)
  • Baseline: 498a0bb3eb92ae1a60ec459e12ce4657b8ee6af2 (498a0bb3eb92ae1a60ec459e12ce4657b8ee6af2)
  • Reviewed: rust-sdk, python-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

state:accepted A maintainer decided OpenShell should pursue this issue

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make the MicroVM sandbox workspace root configurable (currently hard-coded to /sandbox)

1 participant