Skip to main content
Change of provenance

The repository or configuration that created this release differ from a previous release. View details.

OpenShell

Python SDK for OpenShell

License PyPI Security policy Documentation

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

Apache-2.0.

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)

Source distribution for openshell 0.1.8
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)

Table of built distributions (wheels) for openshell 0.1.8
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.8 This release

2 release files Change of provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page