Skip to content
OpenShell
You are viewing OpenShell 0.1.8. The latest version is 0.1.9. Go to the latest version.

Go SDK

Install the OpenShell Go SDK, connect to a gateway, and manage a sandbox.

Use the Go SDK to manage OpenShell resources from Go applications, operators, and controllers. Its typed subclients follow familiar Kubernetes client patterns. Use the SDK and gateway from the same OpenShell release when possible.

The SDK requires Go 1.25.13 or later. Add it to your Go module:

Terminal window
go get github.com/NVIDIA/OpenShell/sdk/go@latest

Pass a host:port address to NewClient. For a local gateway that allows unauthenticated plaintext connections:

package main
import (
"context"
"fmt"
"log"
"time"
v1 "github.com/NVIDIA/OpenShell/sdk/go/openshell/v1"
)
func main() {
client, err := v1.NewClient(v1.Config{
Address: "127.0.0.1:8080",
Auth: v1.NoAuth(),
})
if err != nil {
log.Fatal(err)
}
defer client.Close()
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
defer cancel()
health, err := client.Health().Check(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("gateway healthy: %v\n", health.Healthy)
}

For an authenticated TLS gateway, provide the bearer token and TLS settings:

client, err := v1.NewClient(v1.Config{
Address: "gateway.example.com:443",
Auth: v1.StaticToken(os.Getenv("OPENSHELL_TOKEN")),
TLS: &v1.TLSConfig{CAFile: "/path/to/ca.crt"},
})

Omit CAFile to use system roots. For renewable OIDC service credentials, use oidc.NewClientCredentialsAuth from github.com/NVIDIA/OpenShell/sdk/go/openshell/v1/oidc.

gateway.NewClient("") and gateway.LoadConfig("") select the active gateway from the user active_gateway file first, then fall back to the system /etc/openshell/active_gateway. gateway.ListGateways marks the selected gateway as active, including a system default.

Resource methods take an explicit workspace. The following example creates a sandbox in default, waits for readiness, runs a command, and requests deletion:

sandbox, err := client.Sandboxes().Create(
ctx,
"default",
"sdk-example",
&v1.SandboxSpec{
Template: &v1.SandboxTemplate{
Image: "registry.example.com/team/python-agent:1.0",
},
},
nil,
)
if err != nil {
log.Fatal(err)
}
sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
if err != nil {
log.Fatal(err)
}
result, err := client.Exec().Run(
ctx,
"default",
sandbox.Name,
[]string{"python", "-c", "print('hello from OpenShell')"},
)
if err != nil {
log.Fatal(err)
}
fmt.Print(string(result.Stdout))
if _, err := client.Sandboxes().Delete(ctx, "default", sandbox.Name); err != nil {
log.Fatal(err)
}

The root client also exposes subclients for providers, services, files, SSH, TCP forwarding, policy, configuration, templates, and workspaces. List methods return lazy pagers so callers choose when to fetch the next page.

We are a Cloud Native Computing Foundation sandbox project.