Problem Statement
Users need a concrete Python example that demonstrates how to launch and manage multiple OpenShell sandboxes as a fleet, configure their OCI image and sandbox policy, expose a Jupyter API service from each member, and submit work through the Jupyter protocol. Existing examples do not show this composition or the current boundaries of the Python SDK.
Proposed Design
Add an examples/jupyter-sandbox directory containing:
- A generic context-managed Fleet abstraction that composes multiple independently managed resources and unwinds partially created fleets safely.
- A JupyterSandbox resource that uses SandboxClient for gateway health, sandbox creation, readiness, command execution over stdin, deletion, and deletion confirmation.
- A plain demo.py script with edit-in-place constants for the image, sandbox count, policy, names, gateway, and submitted Python code. The default launches three sandboxes and submits code to the first member through the Jupyter REST and kernel WebSocket APIs.
- A pinned Jupyter-ready Dockerfile and a restrictive policy that denies outbound network access.
- Documentation for building the image, launching the example with python demo.py, and understanding cleanup and token handling.
Each sandbox starts Jupyter on loopback, exposes port 8888 as a named OpenShell service, receives a distinct Jupyter token through sandbox exec stdin, and is removed when the fleet context exits. Until service CRUD is public in the Python SDK, the example uses a narrow openshell service CLI adapter only for expose and delete.
The documentation also proposes the missing Python SDK surface: public service CRUD, public sandbox configuration models, canonical policy YAML loading, and Dockerfile or build-directory image preparation.
Alternatives Considered
- A shell-only example would not demonstrate the requested Python fleet composition or SDK lifecycle.
- Parallel lists of sandboxes and cleanup callbacks would make partial-failure cleanup harder to reason about than context-manager composition.
- Calling private gRPC stubs for service exposure would hide the SDK gap and couple the example more tightly to internal generated APIs.
- Reimplementing Dockerfile builds in the example would duplicate CLI behavior; requiring a prepared OCI image keeps sandbox management focused on the SDK.
Agent Investigation
- Verified SandboxClient supports active-gateway discovery, health, create, wait_ready, exec with stdin, delete, and wait_deleted.
- Verified the public Python SDK does not currently expose service CRUD methods.
- Verified sandbox creation accepts protobuf SandboxSpec values, but the generated spec and policy models live under the private openshell._proto package.
- Verified the CLI policy loader and Dockerfile source resolver do not have Python SDK equivalents.
- Searched open and closed issues for a matching Jupyter sandbox proposal and found no duplicate.
Checklist
Problem Statement
Users need a concrete Python example that demonstrates how to launch and manage multiple OpenShell sandboxes as a fleet, configure their OCI image and sandbox policy, expose a Jupyter API service from each member, and submit work through the Jupyter protocol. Existing examples do not show this composition or the current boundaries of the Python SDK.
Proposed Design
Add an examples/jupyter-sandbox directory containing:
Each sandbox starts Jupyter on loopback, exposes port 8888 as a named OpenShell service, receives a distinct Jupyter token through sandbox exec stdin, and is removed when the fleet context exits. Until service CRUD is public in the Python SDK, the example uses a narrow openshell service CLI adapter only for expose and delete.
The documentation also proposes the missing Python SDK surface: public service CRUD, public sandbox configuration models, canonical policy YAML loading, and Dockerfile or build-directory image preparation.
Alternatives Considered
Agent Investigation
Checklist