|
1 | | -# OpenShell Python SDK |
| 1 | +<picture> |
| 2 | + <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-dark.png"> |
| 3 | + <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-light.png"> |
| 4 | + <img alt="OpenShell" src="https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-light.png" width="430"> |
| 5 | +</picture> |
2 | 6 |
|
3 | | -The `openshell` package is the Python client for the |
4 | | -[OpenShell](https://github.com/NVIDIA/OpenShell) gateway: sandbox lifecycle, |
5 | | -templates, workspaces, exec, and provider credentials, plus the generated gRPC |
6 | | -bindings under `openshell._proto`. |
| 7 | +# Python SDK for OpenShell |
| 8 | + |
| 9 | +[](https://github.com/ai-openshell/sdk-python/blob/main/LICENSE) |
| 10 | +[](https://pypi.org/project/openshell/) |
| 11 | +[](https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md) |
| 12 | +[](https://docs.nvidia.com/openshell/latest/sdk/python) |
| 13 | + |
| 14 | +Use the Python SDK to manage [OpenShell](https://github.com/NVIDIA/OpenShell) sandboxes from applications, notebooks, and automation. Create sandboxes, run commands and Python functions, and manage templates, workspaces, and provider credentials through the gateway. |
| 15 | + |
| 16 | +See the [Python SDK documentation](https://docs.nvidia.com/openshell/latest/sdk/python) for connection options, authentication, and generated gRPC bindings. |
| 17 | + |
| 18 | +## Installation |
| 19 | + |
| 20 | +The SDK requires Python 3.11 or later and a [running OpenShell gateway](https://docs.nvidia.com/openshell/latest/about/installation). Installing the `openshell` package installs only the Python client. |
| 21 | + |
| 22 | +With uv, add the SDK to your project: |
7 | 23 |
|
8 | 24 | ```shell |
9 | | -pip install openshell |
| 25 | +uv add openshell |
10 | 26 | ``` |
11 | 27 |
|
12 | | -The SDK moved here from NVIDIA/OpenShell. The package name, import paths, and |
13 | | -API are unchanged, including `openshell._proto`. Releases published from |
14 | | -NVIDIA/OpenShell stay on PyPI. |
| 28 | +Or install it with pip: |
15 | 29 |
|
16 | | -## Development |
| 30 | +```shell |
| 31 | +pip install -U openshell |
| 32 | +``` |
17 | 33 |
|
18 | | -Tools are managed by [mise](https://mise.jdx.dev/) and dependencies by |
19 | | -[uv](https://docs.astral.sh/uv/). The Python version is pinned in |
20 | | -`.python-version`, which both read. See [CONTRIBUTING.md](CONTRIBUTING.md) for |
21 | | -setup, commit rules and the release model, and [SECURITY.md](SECURITY.md) to |
22 | | -report a vulnerability. |
| 34 | +## Quickstart |
23 | 35 |
|
24 | | -```shell |
25 | | -mise run ci # checks, tests, build, and install smoke test |
26 | | -mise run check # format, lint, typecheck, proto and fixture drift |
27 | | -mise run test # unit tests; UV_PYTHON=3.11 picks the interpreter |
28 | | -mise run proto:gen # regenerate src/openshell/_proto from the pinned protos |
29 | | -mise run core:version |
| 36 | +Before running this example, [start a gateway](https://docs.nvidia.com/openshell/latest/about/installation) or [register an existing running gateway](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/overview#register-an-existing-gateway). Then select it with the CLI. The SDK reuses its endpoint, TLS configuration, and authentication state. |
| 37 | + |
| 38 | +```python |
| 39 | +from openshell import Sandbox |
| 40 | + |
| 41 | +with Sandbox(workspace="default") as sandbox: |
| 42 | + result = sandbox.exec(["echo", "Hello from OpenShell"]) |
| 43 | + print(result.stdout, end="") |
| 44 | + if result.exit_code != 0: |
| 45 | + raise RuntimeError(result.stderr) |
30 | 46 | ``` |
31 | 47 |
|
32 | | -## Core version and generated bindings |
| 48 | +`Sandbox` creates a sandbox, waits for readiness, and deletes it when the context exits. This example uses the gateway's default workload image and the `default` workspace. |
33 | 49 |
|
34 | | -The bindings are generated from `proto/` in NVIDIA/OpenShell at the ref in |
35 | | -`OPENSHELL_CORE_REF` (`mise.toml`, currently `v0.1.7`) and committed under |
36 | | -`src/openshell/_proto`. `buf export` fetches the protos, the same way sdk-go |
37 | | -reads them, and `grpcio-tools` generates the bindings: |
| 50 | +## Usage examples |
38 | 51 |
|
39 | | -- Building a wheel or sdist needs neither a core checkout nor network access. |
40 | | -- A change of the pin shows the effect on the generated API in its diff. |
41 | | -- `mise run proto:check` fails when the committed bindings differ from the |
42 | | - pinned protos, and `mise run conformance:check` does the same for the |
43 | | - vendored test fixtures and `tests/e2e/Dockerfile.workload`. |
| 52 | +### Check SDK and gateway versions |
44 | 53 |
|
45 | | -## E2E tests |
| 54 | +Connect to the active gateway and print both versions: |
46 | 55 |
|
47 | | -`tests/e2e` runs against a real gateway; `mise run test` skips it. CI runs it |
48 | | -against the published gateway of the pinned core version, with the Docker |
49 | | -compute driver. To run it locally, you need Docker with the compose plugin: |
| 56 | +```python |
| 57 | +import openshell |
| 58 | +from openshell import SandboxClient |
50 | 59 |
|
51 | | -```shell |
52 | | -mise run e2e:image |
53 | | -scripts/e2e/start-gateway.sh "$(mise run -q core:version)" --default-image openshell/e2e-python:dev |
54 | | -OPENSHELL_GATEWAY=e2e mise run e2e |
55 | | -scripts/e2e/stop-gateway.sh |
| 60 | +print(f"SDK version: {openshell.__version__}") |
| 61 | +with SandboxClient.from_active_cluster() as client: |
| 62 | + print(f"Gateway version: {client.health().version}") |
| 63 | +``` |
| 64 | + |
| 65 | +Pass `cluster="my-gateway"` to select a registered gateway by name. For OIDC gateways, the client refreshes expiring tokens and saves the updated token bundle by default. |
| 66 | + |
| 67 | +### List sandboxes |
| 68 | + |
| 69 | +Sandbox operations require an explicit workspace. List methods return a lazy `Pager`, which fetches one page at a time: |
| 70 | + |
| 71 | +```python |
| 72 | +from openshell import SandboxClient |
| 73 | + |
| 74 | +with SandboxClient.from_active_cluster() as client: |
| 75 | + for page in client.list(workspace="default", page_size=100): |
| 76 | + for sandbox in page.items: |
| 77 | + print(sandbox.name, sandbox.id) |
56 | 78 | ``` |
57 | 79 |
|
58 | | -`e2e:image` builds the sandbox image from `tests/e2e/Dockerfile.workload`, a |
59 | | -copy of core's, with the Python version from `.python-version` and |
60 | | -`cloudpickle`, so `Sandbox.exec_python` can run the client's callables. |
| 80 | +Use `client.list_all(workspace="default")` to collect every page into a list. |
| 81 | + |
| 82 | +### Run commands in an existing sandbox |
| 83 | + |
| 84 | +Use `sandbox` to attach by name. Set `delete_on_exit=False` to keep the sandbox after the context exits: |
| 85 | + |
| 86 | +```python |
| 87 | +from openshell import Sandbox |
| 88 | + |
| 89 | +with Sandbox( |
| 90 | + workspace="default", |
| 91 | + sandbox="my-sandbox", |
| 92 | + delete_on_exit=False, |
| 93 | +) as sandbox: |
| 94 | + result = sandbox.exec( |
| 95 | + ["sh", "-c", "echo Starting; ls /tmp"], |
| 96 | + stream_output=True, |
| 97 | + timeout_seconds=30, |
| 98 | + ) |
| 99 | + print(f"Exit code: {result.exit_code}") |
| 100 | +``` |
| 101 | + |
| 102 | +`exec()` returns an `ExecResult` with `stdout`, `stderr`, and `exit_code`. With `stream_output=True`, it also prints output as it arrives. |
| 103 | + |
| 104 | +### Authenticate service automation |
| 105 | + |
| 106 | +For an OIDC gateway that supports the OAuth client credentials flow, supply a renewable authentication provider: |
| 107 | + |
| 108 | +```python |
| 109 | +import os |
| 110 | + |
| 111 | +from openshell import ClientCredentialsAuth, SandboxClient |
| 112 | + |
| 113 | +auth = ClientCredentialsAuth( |
| 114 | + issuer="https://idp.example.com/realms/openshell", |
| 115 | + client_id="openshell-service", |
| 116 | + client_secret=lambda: os.environ["OPENSHELL_OIDC_CLIENT_SECRET"], |
| 117 | + audience="openshell-gateway", |
| 118 | +) |
| 119 | + |
| 120 | +with SandboxClient.from_active_cluster(client_credentials=auth) as client: |
| 121 | + print(client.health().version) |
| 122 | +``` |
| 123 | + |
| 124 | +Configure the issuer, client ID, and audience for your identity provider. Non-loopback gateway connections using client credentials require TLS. See [gateway authentication](https://docs.nvidia.com/openshell/latest/how-it-works/gateways/authentication) for setup. |
| 125 | + |
| 126 | +## Documentation |
| 127 | + |
| 128 | +- [Python SDK guide](https://docs.nvidia.com/openshell/latest/sdk/python): connections, provider credentials, and generated RPCs. |
| 129 | +- [Sandboxes](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview): lifecycle, workload images, and templates. |
| 130 | +- [API errors](https://docs.nvidia.com/openshell/latest/sdk/api-errors): structured gateway errors and error handling. |
| 131 | + |
| 132 | +The package includes generated gRPC bindings under `openshell._proto` for access to the underlying gateway API. `SandboxClient` is synchronous; generated stubs support synchronous and asynchronous gRPC channels. |
| 133 | + |
| 134 | +## Supported core versions |
| 135 | + |
| 136 | +Use SDK and gateway versions from the same OpenShell release when possible. SDK releases follow core releases: SDK `X.Y.Z` is built from core `vX.Y.Z`. |
| 137 | + |
| 138 | +The generated bindings currently target core `v0.1.7`, pinned by `OPENSHELL_CORE_REF` in `mise.toml`. |
| 139 | + |
| 140 | +## Contributing |
| 141 | + |
| 142 | +See [CONTRIBUTING.md](https://github.com/ai-openshell/sdk-python/blob/main/CONTRIBUTING.md) for development setup, checks, end-to-end tests, and release conventions. The project uses [mise](https://mise.jdx.dev/) for tools and [uv](https://docs.astral.sh/uv/) for Python dependencies. |
| 143 | + |
| 144 | +Report vulnerabilities through the [security policy](https://github.com/ai-openshell/sdk-python/blob/main/SECURITY.md). |
61 | 145 |
|
62 | | -`start-gateway.sh` is meant for throwaway hosts. It registers `e2e` as the |
63 | | -active gateway, and `stop-gateway.sh` removes every sandbox container labelled |
64 | | -with core's default namespace. Set `XDG_CONFIG_HOME` to keep your own gateway |
65 | | -registrations apart. |
| 146 | +## Repository history |
66 | 147 |
|
67 | | -## History |
| 148 | +The SDK moved from NVIDIA/OpenShell to this repository. The PyPI package name, import paths, and API are unchanged, including `openshell._proto`. Earlier releases remain available on PyPI. |
68 | 149 |
|
69 | | -The history up to the move was imported from NVIDIA/OpenShell at `v0.1.7`. |
70 | | -The scripts that extracted and verified it are not on `main`. They are kept at |
71 | | -the `migration/v0.1.7` tag, in |
72 | | -[hack/migration](https://github.com/ai-openshell/sdk-python/tree/migration/v0.1.7/hack/migration). |
| 150 | +History through core `v0.1.7` was imported from NVIDIA/OpenShell. The extraction and verification scripts are preserved under [hack/migration at the migration/v0.1.7 tag](https://github.com/ai-openshell/sdk-python/tree/migration/v0.1.7/hack/migration). |
73 | 151 |
|
74 | 152 | ## License |
75 | 153 |
|
76 | | -Apache-2.0. See [LICENSE](LICENSE). |
| 154 | +[Apache-2.0](https://github.com/ai-openshell/sdk-python/blob/main/LICENSE). |
0 commit comments