Skip to main content
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.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for openshell 0.1.9
File Size Uploaded Provenance Actions
openshell-0.1.9.tar.gz 230.6 kB With provenance Details for openshell-0.1.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for openshell 0.1.9
File Interpreter ABI Platform Actions
openshell-0.1.9-py3-none-any.whl Python 3 none any Details for openshell-0.1.9-py3-none-any.whl

Total release size: 364.6 kB

Release files / openshell-0.1.9.tar.gz

Download URL openshell-0.1.9.tar.gz
Size 230.6 kB
Tags Source
SHA-256 checksum
How to use checksums
dd61158edaf3c89e405430aa6c6ff00a0ea6feb8124ca29ed63abbdd3d521ffd
BLAKE2b-256 checksum
How to use checksums
d4948d11588308dd48d30950e14a84c45a1da033950a046c32aa0f5e87ca4401
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 17, 2026.

Transparency log

Release files / openshell-0.1.9-py3-none-any.whl

Download URL openshell-0.1.9-py3-none-any.whl
Size 134.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5805829ef04b98d84dd6b2f4707f079c87bf8a4225a516b3b11bc6f84d56a9be
BLAKE2b-256 checksum
How to use checksums
e844c812c8d9a2f510f54f3c6a2e5ce492a0b50a2a002173f19a6d263d2edcc3
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 17, 2026.

Transparency log

Security for openshell 0.1.9

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for openshell-0.1.9.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 17, 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.9 This release

2 release files Full 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