Upgrading OpenShell independently breaks NemoClaw sandbox — version coupling should be documented

[W4k4s]

Upgrading OpenShell independently breaks NemoClaw sandbox — version coupling should be documented

Environment

• NemoClaw: 0.1.0
• OpenShell: 0.0.7 (pinned by NemoClaw), accidentally upgraded to 0.0.8
• OS: Ubuntu 22.04.5 LTS
• Container runtime: k3s v1.29 (containerd)

Problem

NemoClaw 0.1.0 ships with and expects OpenShell 0.0.7. This version coupling is not documented anywhere — not in the README, not in the onboarding output, and not in nemoclaw --version.

When we ran openshell self-update (thinking it was a safe, independent upgrade), OpenShell upgraded to 0.0.8. On the next sandbox recreation, the sandbox environment changed fundamentally:

• The agent inside the sandbox switched from OpenClaw to Claude Code
• Workspace scaffolding changed (different default files, different directory layout)
• Skills and tools that depended on OpenClaw internals stopped working
• The Teams integration continued to route messages, but the agent behavior was completely different

The root cause: OpenShell 0.0.8 apparently bundles a different agent runtime than 0.0.7, and NemoClaw's configuration assumes the 0.0.7 sandbox layout.

Steps to Reproduce

1. Deploy NemoClaw 0.1.0 via nemoclaw onboard — everything works, OpenShell 0.0.7 is installed
2. Run openshell self-update (or npm update -g openshell)
3. OpenShell updates to latest (0.0.8+)
4. Restart the pod, or run openshell gateway start --recreate
5. Result: Sandbox is rebuilt with the new OpenShell version; agent runtime inside changes; NemoClaw's expected workspace layout no longer matches

Alternatively:

1. Run openshell sandbox create directly instead of going through nemoclaw onboard
2. Result: Same breakage — sandbox is created with OpenShell defaults instead of NemoClaw's expected configuration

Recovery

We had to:

1. Downgrade OpenShell: npm install -g openshell@0.0.7
2. Re-run nemoclaw onboard to rebuild the sandbox with the correct version
3. Restore workspace from backup (see #[pvc-persistence-issue] for our backup approach)

Total downtime: ~30 minutes, plus loss of any workspace changes since the last backup.

Current Workaround

• Pin OpenShell in our deployment scripts: npm install -g openshell@0.0.7 (never @latest)
• Added a pre-flight check in our startup scripts that verifies the OpenShell version matches expectations:

  EXPECTED_OPENSHELL="0.0.7"
  ACTUAL_OPENSHELL=$(openshell --version 2>/dev/null | grep -oP '\d+\.\d+\.\d+')
  if [ "$ACTUAL_OPENSHELL" != "$EXPECTED_OPENSHELL" ]; then
    echo "ERROR: OpenShell version mismatch. Expected $EXPECTED_OPENSHELL, got $ACTUAL_OPENSHELL"
    echo "Run: npm install -g openshell@$EXPECTED_OPENSHELL"
    exit 1
  fi

• Never run openshell commands directly — always go through nemoclaw CLI

Expected Behavior / Suggestion

1. Document the version dependency. The NemoClaw README and nemoclaw onboard output should clearly state which OpenShell version is required and that independent upgrades are not supported.

2. Add a compatibility matrix. A table mapping NemoClaw versions to their required OpenShell versions:

   NemoClaw	OpenShell	Notes
   0.1.0	0.0.7	Initial release
   0.2.0	TBD	—

3. Version check at startup. NemoClaw should detect the installed OpenShell version on startup and warn (or refuse to start) if it's incompatible:

   ⚠️  NemoClaw 0.1.0 requires OpenShell 0.0.7, but 0.0.8 is installed.
       Run `npm install -g openshell@0.0.7` or upgrade NemoClaw.
   

4. Lock the upgrade path. Ideally, openshell self-update should be aware that it's being managed by NemoClaw and either refuse to upgrade or warn the user. Alternatively, NemoClaw could install OpenShell as a local dependency rather than a global one, making accidental upgrades impossible.

5. Clarify CLI boundaries. Document that users should always use nemoclaw onboard / nemoclaw start and should never run openshell gateway start --recreate or openshell sandbox create directly when NemoClaw is managing the deployment.

The tight coupling between NemoClaw and OpenShell is understandable at this stage, but it needs to be visible to operators. A silent version mismatch that changes the agent runtime is a significant operational risk.

[13ernkastel]

Fixed by open PR #1263: #1263

[13ernkastel]

Fixed by open PR #1263: #1263

I do not have permission to close issues in this repo from this account, so leaving this for a maintainer to close on review or merge.

[prekshivyas]

Closing this in favor of mereged PR #1263