Skip to content

docs: OpenShell 0.0.115 macOS release binaries are Nix-linked and do not start; install guide points Apple Silicon users at it #6707

New issue
New issue
Closed
Closed
docs: OpenShell 0.0.115 macOS release binaries are Nix-linked and do not start; install guide points Apple Silicon users at it#6707
Labels
bugcomponent/docsUser-facing documentationcomponent/installCLI install and app setupcomponent/sandboxOpenShell sandbox environmentpr-openAn open PR already addresses this issuepriority/highSignificant impact, address soontype/bugConfirmed defect in existing behavior

Description

@waynesun09
waynesun09
opened on Aug 27, 2026

What happened

#6696 (closes #6691) moved the OpenShell pin to 0.0.115 and updated the install snippet in docs/guides/user/running-agents-locally.md to match (OPENSHELL_VERSION=0.0.115 piped through the upstream install.sh).

On Apple Silicon that snippet installs a build that does not start. All three aarch64-apple-darwin binaries in the 0.0.115 release (CLI, gateway, and VM driver) are dynamically linked against a Nix store path that only exists on the upstream build host:

dyld[66826]: Library not loaded: /nix/store/x66vl94b37qshkwsbcwsa6izzl36467a-libiconv-115.100.1/lib/libiconv.2.dylib
  Referenced from: /opt/homebrew/Cellar/openshell/0.0.115/bin/openshell

otool -L confirms the identical reference in openshell-gateway and openshell-driver-vm. The Homebrew formula's post-install fails at openshell-gateway generate-certs with the same error, so brew reinstall leaves the user with a dead CLI and a gateway service that cannot start. The raw openshell-gateway-aarch64-apple-darwin.tar.gz release asset carries the same link, so this is not specific to the Homebrew path.

Verified on macOS 26 (arm64):

Release macOS CLI / gateway / VM driver Notes
v0.0.111 clean first release with the 0.0.111+ main-process lifecycle #6691 targets
v0.0.113 clean last published macOS release (v0.0.114 was tagged, but its release run failed on an unrelated e2e job)
v0.0.115 broken /nix/store/...libiconv.2.dylib in all three binaries

CI is unaffected: the Linux binaries are normalized (static musl CLI, glibc 2.28 gateway with the Nix RPATH stripped), and functional-tests / e2e passed on 0.0.115 in #6696.

Root cause (upstream)

NVIDIA/OpenShell#2977 (ci: build release binaries with Nix, merged 2026-08-27 17:35 UTC) replaced the release build with a Nix-based workflow; v0.0.115 was published 28 minutes later. In .github/actions/build-rust-binary/action.yml the Normalize Linux dynamic binary step (patchelf --set-interpreter … --remove-rpath) is gated if: endsWith(inputs.triple, '-linux-gnu') and Verify static linkage on -linux-musl; there is no step for -apple-darwin, so the darwin binaries built inside nix develop .#devShells.aarch64-darwin.default keep the Nix install-name for libiconv. The action's Verify step runs <binary> --version inside that same nix develop shell, where the store path exists on the runner, so the release run (33100034661) is green despite shipping binaries that cannot start elsewhere. The PR's own checklist leaves "Apple Silicon build matrix passes in GitHub Actions" unchecked.

Reported upstream as NVIDIA/OpenShell#2997.

Verified workaround

The release binaries are ad-hoc, linker-signed, and the formula itself ad-hoc signs its VM driver, so re-pointing the library and re-signing stays within the package's own conventions. /usr/lib/libiconv.2.dylib is not present as a file on recent macOS but is in the dyld shared cache and loads:

for b in openshell openshell-gateway; do
  install_name_tool -change \
    /nix/store/x66vl94b37qshkwsbcwsa6izzl36467a-libiconv-115.100.1/lib/libiconv.2.dylib \
    /usr/lib/libiconv.2.dylib "/opt/homebrew/Cellar/openshell/0.0.115/bin/$b"
  codesign --force -s - "/opt/homebrew/Cellar/openshell/0.0.115/bin/$b"
done
brew services restart nvidia/openshell/openshell

With that applied, sandbox create --detach -- sleep infinity reaches Ready in ~3s, sandbox exec works, -- true fails with MainProcessExited: Canonical main process exited as #6691 describes, and a full fullsend run --runtime dummy against the local Podman gateway completes with exit 0. Any later brew reinstall / brew postinstall nvidia/openshell/openshell reverts it.

Proposed change

Out of scope

Validation criteria

  • Following the "Install OpenShell" section verbatim on a clean Apple Silicon Mac yields a working openshell --version and openshell status.
  • The caveat is removed in the same PR that bumps the pin to a release whose openshell-aarch64-apple-darwin.tar.gz has no /nix/store reference in otool -L.

References

Activity

  1. waynesun09
    added
    type/bugConfirmed defect in existing behavior
    component/sandboxOpenShell sandbox environment
    component/docsUser-facing documentation
    on Aug 27, 2026
  2. github-project-automation
    added this to fullsend-ai Workstreamon Aug 27, 2026
  3. github-project-automation
    moved this to Todo in fullsend-ai Workstreamon Aug 27, 2026

  4. fullsend-ai-triage commented on Aug 27, 2026

    @fullsend-ai-triage
    fullsend-ai-triageBot
    on Aug 27, 2026 – with fullsend-ai-triage

    🤖 Finished Triage · ✅ Success · Started 9:40 PM UTC · Completed 9:45 PM UTC

    Commit: 96d46c8 · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.60

  5. fullsend-ai-triage
    added
    bug
    priority/highSignificant impact, address soon
    component/installCLI install and app setup
    ready-to-codeTriggers code agent dispatch
    on Aug 27, 2026

  6. fullsend-ai-triage commented on Aug 27, 2026

    @fullsend-ai-triage
    fullsend-ai-triageBot
    on Aug 27, 2026 – with fullsend-ai-triage

    Triage summary

    Severity: high — blocks all Apple Silicon local development; Linux CI unaffected.

    The proposed docs-only fix (pin macOS users to 0.0.113, document the install_name_tool workaround) can proceed immediately since 0.0.113 already has the 0.0.111+ lifecycle semantics required by #6691.

    A separate upstream issue should be filed at NVIDIA/OpenShell for the macOS binary normalization gap introduced in #2977 — their PR checklist explicitly left the Apple Silicon build matrix item unchecked.

    Proposed test case

    Given: a clean Apple Silicon Mac following the updated install guide
When:  the user runs the documented install snippet
Then:  `openshell --version` succeeds without dyld errors
 And:  `openshell status` returns without error
 And:  `otool -L $(which openshell)` contains no /nix/store references

    Labels: High priority due to blocking Apple Silicon local development; component/install applies since the fix targets the install documentation and process.

    Next steps:

    • /fs-code — agent creates a PR to implement this issue
    • /fs-code <your instruction> — agent implements with your specific guidance

  7. fullsend-ai-coder commented on Aug 27, 2026

    @fullsend-ai-coder
    fullsend-ai-coderBot
    on Aug 27, 2026 – with fullsend-ai-coder
    Contributor

    🤖 Finished Code · ✅ Success · Started 9:46 PM UTC · Completed 9:52 PM UTC

    Commit: 96d46c8 · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $1.25

  8. github-project-automation
    moved this from Todo to In progress in fullsend-ai Workstreamon Aug 27, 2026

  9. fullsend-ai-triage commented on Aug 27, 2026

    @fullsend-ai-triage
    fullsend-ai-triageBot
    on Aug 27, 2026 – with fullsend-ai-triage

    🤖 Finished Triage · ✅ Success · Started 11:54 PM UTC · Completed 11:57 PM UTC

    Commit: b13c0b1 · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.69

  10. fullsend-ai-triage
    added
    pr-openAn open PR already addresses this issue
    and removed
    ready-to-codeTriggers code agent dispatch
    on Aug 27, 2026

  11. fullsend-ai-triage commented on Aug 27, 2026

    @fullsend-ai-triage
    fullsend-ai-triageBot
    on Aug 27, 2026 – with fullsend-ai-triage

    Work on this issue continues via the open PR. Since the last triage, the upstream issue has been filed at NVIDIA/OpenShell#2997 — that was the remaining action item from the original issue description.

    The review on the PR raised a medium finding worth addressing before merge: the install_name_tool workaround hardcodes a Homebrew Cellar path, but users who installed via the curl-based script documented earlier in the guide would have binaries elsewhere. Consider using $(which openshell) or adding a note that the workaround is Homebrew-specific.

    Addressed by:

    Previous run

    A PR is already in flight that adds the macOS Apple Silicon caveat to the install guide, recommending v0.0.113 and documenting the install_name_tool workaround. The review surfaced a medium finding about the workaround hardcoding Homebrew paths (users who installed via the curl script would have binaries elsewhere) — that may need addressing before merge.

    Note: the issue also calls for filing an upstream issue at NVIDIA/OpenShell for the Nix build regression introduced in their #2977. That upstream report is independent of the docs fix and should still be filed separately.

    Addressed by:

  12. waynesun09 commented on Aug 28, 2026

    @waynesun09
    waynesun09
    on Aug 28, 2026
    MemberAuthor

    Filed upstream as NVIDIA/OpenShell#2997 (labels os:macos, area:build). The upstream report carries the full mechanism: darwin binaries are built in nix develop, only -linux-gnu/-linux-musl get the normalize/verify steps, and the action's own --version smoke check runs inside the Nix shell where the store path resolves.

  13. fullsend-ai-triage commented on Aug 28, 2026

    @fullsend-ai-triage
    fullsend-ai-triageBot
    on Aug 28, 2026 – with fullsend-ai-triage

    🤖 Finished Triage · ✅ Success · Started 12:03 AM UTC · Completed 12:06 AM UTC

    Commit: b13c0b1 · View workflow run →

    Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.65

  14. fullsend-ai-triage
    added
    pr-openAn open PR already addresses this issue
    and removed
    pr-openAn open PR already addresses this issue
    on Aug 28, 2026
  15. waynesun09
    added a commit that references this issue on Aug 28, 2026

    chore(deps): move the OpenShell pin mirrors to 0.0.116

    5932b2f

  16. waynesun09 commented on Aug 28, 2026

    @waynesun09
    waynesun09
    on Aug 28, 2026
    MemberAuthor

    Upstream shipped the fix: NVIDIA/OpenShell#3006 (Closes NVIDIA/OpenShell#2997) landed in OpenShell v0.0.116 (2026-08-28). I verified the v0.0.116 openshell and openshell-gateway aarch64-apple-darwin tarballs carry no /nix/store reference and run unpatched.

    So the resolution is simpler than the caveat proposed above: just point the guide at 0.0.116. That is done in #6737 (the Renovate pin bump plus a commit moving the hand-maintained mirrors, including the running-agents-locally.md snippet); the commit carries Closes #6707, so this closes when #6737 merges.

  17. waynesun09 commented on Aug 28, 2026

    @waynesun09
    waynesun09
    on Aug 28, 2026
    MemberAuthor

    Resolved by #6737 (merged 2026-08-28, 5b796658): the pin moved to OpenShell 0.0.116, which ships the upstream macOS fix (NVIDIA/OpenShell#3006, closes NVIDIA/OpenShell#2997), and docs/guides/user/running-agents-locally.md now points macOS users at that build. The Closes keyword in commit 5932b2f2 did not fire through the merge queue, hence the manual close.

  18. waynesun09
    closed this as completedon Aug 28, 2026
  19. github-project-automation
    moved this from In progress to Done in fullsend-ai Workstreamon Aug 28, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugcomponent/docsUser-facing documentationcomponent/installCLI install and app setupcomponent/sandboxOpenShell sandbox environmentpr-openAn open PR already addresses this issuepriority/highSignificant impact, address soontype/bugConfirmed defect in existing behavior

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions