feat(examples): run Jupyter notebooks in an OpenShell sandbox

[drew]

Summary

Show a three-step CLI workflow: install a notebook CLI, start a published Jupyter image as an exposed OpenShell service, and execute a local notebook on its sandboxed kernel using URL and token flags.

Related Issue

Related to #2252. This example now follows the requested CLI workflow and does not implement the Python SDK example proposed in that issue, so it does not close it.

Changes

• Use the published quay.io/jupyter/base-notebook:2026-04-27 image directly; remove the custom Dockerfile.
• Start token-authenticated Jupyter Server with openshell sandbox create --expose 8888 --detach -- jupyter server ....
• Use nb execute --gateway <service-url> --gateway-token <token> to run notebook cells in the remote kernel and write outputs back to the local notebook.
• Match the policy to the image's jovyan user, users group, and /home/jovyan workspace; keep outbound network access denied.
• Remove the nbconvert JSON config and the extra executed-notebook file and ignore rule.

Stock jupyter nbconvert ignores --GatewayClient.url when used with its remote kernel manager, so a URL flag would not reach the gateway. The Jupyter community nb CLI supports URL and token flags for REST and WebSocket kernel execution.

Testing

• mise run pre-commit
• Pulled and inspected the published Jupyter image: Jupyter Server 2.17.0, ipykernel 7.2.0, user jovyan:users, writable /home/jovyan
• nb-cli 0.0.10 executed demo.ipynb through a token-authenticated Jupyter Server in the published image; local notebook output was 285
• mise run test: 1396 supervisor-network tests passed; the unchanged plaintext_websocket_middleware_inspects_compressed_ws_messages test timed out in the full suite and passed in isolation. The previous full-suite run had a different passing-in-isolation proxy test fail.
• Live OpenShell sandbox run: no configured local gateway is reachable (openshell status reports connection refused).

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Example README documents the behavior; no architecture boundary changed

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[drew]

gator-agent

Blocked

Gator is blocked because this PR is still marked as draft and is not ready for review.

Head SHA: 7748ad8392767b3b94171fd958c0c28332f43532

Next action: @drew, mark the PR ready for review when it is ready for the gator review and CI monitoring workflow.

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.