OpenShell.Net: .NET (C#) SDK for NVIDIA OpenShell

.NET client for the NVIDIA OpenShell gateway. It targets net8.0 and net10.0 (apps on .NET 11 use the net10.0 build, and the tests also run on .NET 11), is trimming and AOT compatible, and exposes a curated, async API over the gateway's gRPC contract.

This is a community project. It is not affiliated with, endorsed by, or supported by NVIDIA. Report problems in this repository's issues, not upstream.

The generated protobuf bindings come from the proto/ files of the OpenShell release recorded in UPSTREAM_VERSION. Use a gateway from that release or a compatible one: curated methods stay compatible while the underlying RPC contracts do. PARITY.md tracks which gateway features the SDK covers.

Versions

The package version is the NVIDIA OpenShell release the SDK is built from, with a fourth number for SDK-only releases in between:

Package version	Built from OpenShell
0.1.7	v0.1.7
0.1.7.1, 0.1.7.2, ...	v0.1.7, with SDK fixes and additions
0.1.8	v0.1.8

So OpenShell.Net 0.1.7.x pairs with an OpenShell 0.1.7 gateway. While OpenShell is at 0.x, an SDK-only release can also change the SDK's API; the release notes say so. The assembly metadata OpenShellUpstreamRelease records the release at run time.

Parity

Built from NVIDIA OpenShell v0.1.7, the client covers all 67 user-facing gateway RPCs plus the SandboxUpdates service, and targets the union of the Go, Rust, TypeScript, and Python SDKs. It is integration-tested against a real v0.1.7 gateway in CI. See the feature parity summary and PARITY.md for details.

Install

The packages are published to nuget.org:

dotnet add package OpenShell.Net

Package	Contents
OpenShell.Net	The client: every user-facing RPC, authentication, OIDC, gateway discovery, edge tunnel, retries, telemetry
OpenShell.Net.DependencyInjection	AddOpenShell, the AddOpenShellClient builder, and an ASP.NET health check
OpenShell.Net.Testing	FakeOpenShellClient, an in-memory gateway for unit tests

The public API lives in the OpenShell namespace, and the assemblies are named OpenShell.Sdk*.

Quick start

Create one OpenShellClient and reuse it. The client connects lazily, so call Health.CheckAsync() when startup must verify that the gateway is reachable.

using OpenShell;

using var client = new OpenShellClient(new OpenShellClientOptions
{
    Address = new Uri("https://gateway.example.com"),
    Auth = Auth.StaticToken(Environment.GetEnvironmentVariable("OPENSHELL_TOKEN")!),
});

var health = await client.Health.CheckAsync();
Console.WriteLine($"{health.Status}: {health.Version}");

var sandbox = await client.Sandboxes.CreateAsync(
    "sdk-example",
    new SandboxSpec { Image = "registry.example.com/team/python-agent:1.0" });

try
{
    await client.Sandboxes.WaitReadyAsync(sandbox.Name, new WaitOptions { Timeout = TimeSpan.FromMinutes(2) });

    var result = await client.Exec.RunAsync(
        sandbox.Name,
        ["python", "-c", "print('hello from OpenShell')"]);
    Console.WriteLine(result.StdoutText);
}
finally
{
    // Delete the sandbox even when the wait or the command throws.
    var deletion = await client.Sandboxes.DeleteAsync(sandbox.Name);
    if (deletion.Outcome == DeletionOutcome.Accepted)
    {
        await client.Sandboxes.WaitDeletedAsync(
            sandbox.Name,
            new WaitOptions { ExpectedSandboxId = deletion.ResourceId });
    }
}

DeleteAsync returns a typed DeletionResult, not a boolean. Accepted means cleanup is still pending, Unspecified does not establish completion, and IsComplete is true only for Completed and AlreadyAbsent. A missing target is an error unless you pass new DeleteOptions { AllowMissing = true }.

Documentation

The full documentation is at zcsizmadia.github.io/OpenShell.Net:

• Getting started: installation, connecting to a gateway (explicit endpoint, a gateway registered by the OpenShell CLI, or a DI host), and a first program.
• Guides:
  • Connecting: authentication (tokens, OIDC, mTLS, Cloudflare Access), gateway discovery, dependency injection, multi-replica gateways.
  • Sandboxes and their contents: sandboxes (lifecycle, suspend and resume, updates, endpoint status), exec and streaming, networking (TCP forwarding, SSH, services), files and rootfs.
  • Configuration: providers, policy, workspaces and pagination.
  • Behaviour and diagnostics: retries, errors, observability.
  • Other: testing with the fake gateway, raw gRPC access, versioning.
• API reference for all three packages.

Every C# snippet in the guides is compiled, and most are run against the fake gateway, by the Docs workflow. The sources are in docs/.

Contributing

Building from source, the CI script, integration tests against a real gateway, syncing with NVIDIA OpenShell, and mutation testing are described in CONTRIBUTING.md.

License

Apache-2.0. See LICENSE and NOTICE. The vendored protos and fixtures are Copyright NVIDIA Corporation & Affiliates, also under Apache-2.0.