The repository or configuration that created this release differ from a previous release. View details.
Python SDK for OpenShell
Use the Python SDK to manage OpenShell sandboxes from applications, notebooks, and automation. Create sandboxes, run commands and Python functions, and manage templates, workspaces, and provider credentials through the gateway.
See the Python SDK documentation for connection options, authentication, and generated gRPC bindings.
Installation
The SDK requires Python 3.11 or later and a running OpenShell gateway. Installing the openshell package installs only the Python client.
With uv, add the SDK to your project:
uv add openshell
Or install it with pip:
pip install -U openshell
Quickstart
Before running this example, start a gateway or register an existing running gateway. Then select it with the CLI. The SDK reuses its endpoint, TLS configuration, and authentication state.
from openshell import Sandbox
with Sandbox(workspace="default") as sandbox:
result = sandbox.exec(["echo", "Hello from OpenShell"])
print(result.stdout, end="")
if result.exit_code != 0:
raise RuntimeError(result.stderr)
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.
Usage examples
Check SDK and gateway versions
Connect to the active gateway and print both versions:
import openshell
from openshell import SandboxClient
print(f"SDK version: {openshell.__version__}")
with SandboxClient.from_active_cluster() as client:
print(f"Gateway version: {client.health().version}")
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.
List sandboxes
Sandbox operations require an explicit workspace. List methods return a lazy Pager, which fetches one page at a time:
from openshell import SandboxClient
with SandboxClient.from_active_cluster() as client:
for page in client.list(workspace="default", page_size=100):
for sandbox in page.items:
print(sandbox.name, sandbox.id)
Use client.list_all(workspace="default") to collect every page into a list.
Run commands in an existing sandbox
Use sandbox to attach by name. Set delete_on_exit=False to keep the sandbox after the context exits:
from openshell import Sandbox
with Sandbox(
workspace="default",
sandbox="my-sandbox",
delete_on_exit=False,
) as sandbox:
result = sandbox.exec(
["sh", "-c", "echo Starting; ls /tmp"],
stream_output=True,
timeout_seconds=30,
)
print(f"Exit code: {result.exit_code}")
exec() returns an ExecResult with stdout, stderr, and exit_code. With stream_output=True, it also prints output as it arrives.
Authenticate service automation
For an OIDC gateway that supports the OAuth client credentials flow, supply a renewable authentication provider:
import os
from openshell import ClientCredentialsAuth, SandboxClient
auth = ClientCredentialsAuth(
issuer="https://idp.example.com/realms/openshell",
client_id="openshell-service",
client_secret=lambda: os.environ["OPENSHELL_OIDC_CLIENT_SECRET"],
audience="openshell-gateway",
)
with SandboxClient.from_active_cluster(client_credentials=auth) as client:
print(client.health().version)
Configure the issuer, client ID, and audience for your identity provider. Non-loopback gateway connections using client credentials require TLS. See gateway authentication for setup.
Documentation
- Python SDK guide: connections, provider credentials, and generated RPCs.
- Sandboxes: lifecycle, workload images, and templates.
- API errors: structured gateway errors and error handling.
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.
Supported core versions
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.
The generated bindings currently target core v0.1.7, pinned by OPENSHELL_CORE_REF in mise.toml.
Contributing
See CONTRIBUTING.md for development setup, checks, end-to-end tests, and release conventions. The project uses mise for tools and uv for Python dependencies.
Report vulnerabilities through the security policy.
Repository history
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.
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.
License
Metadata
Release files for openshell 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Change of provenance
The repository or configuration that created these release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openshell-0.1.8.tar.gz | 226.2 kB | With provenance | Details for openshell-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openshell-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for openshell-0.1.8-py3-none-any.whl |
Total release size: 358.8 kB
Release files / openshell-0.1.8.tar.gz
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | openshell-0.1.8.tar.gz |
|---|---|
| Size | 226.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6be219b012f0120eeb95670afca570f96300f7d3e1f8865cd5300a34fd501148
|
|
BLAKE2b-256 checksum How to use checksums |
1926dfc96e19e33ffa97f261905dead166c7086aaf7a6692304d0c5dcdf01736
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / openshell-0.1.8-py3-none-any.whl
Change of provenance
This file belongs to a release with changed provenance: the repository or configuration that created the release files differ from that of a previous release.
We recommend inspecting the repository and configuration before proceeding. View details.
| Download URL | openshell-0.1.8-py3-none-any.whl |
|---|---|
| Size | 132.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4f2c802933b34eb20b4bf0cd6cb79bfc085bbb2b3fcb934772f30d6ff5ad7bfd
|
|
BLAKE2b-256 checksum How to use checksums |
1d4a4e06ff5d0e1ffabad396dfbe31355629203b846d35b1d99d940098fa4141
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for openshell 0.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Change of provenance
The repository and configuration that created this release differ from a previous release.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Repository
- Removed 0.1.7 github.com/NVIDIA/OpenShell
- Added 0.1.8 github.com/ai-openshell/sdk-python
Attestation for openshell-0.1.8.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.