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.
Install the SDK
Section titled “Install the SDK”The SDK requires Go 1.25.13 or later. Add it to your Go module:
go get github.com/NVIDIA/OpenShell/sdk/go@latestConnect to a Gateway
Section titled “Connect to a Gateway”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.
Create and Use a Sandbox
Section titled “Create and Use a Sandbox”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.
Next Steps
Section titled “Next Steps”- Review Gateway Authentication before connecting a service to a production gateway.
- Review API Errors for the gateway error model.
- Browse the Go package reference for all exported types and methods.
We are a Cloud Native Computing Foundation sandbox project.
Copyright OpenShell a Series of LF Projects, LLC
For website terms of use, trademark policy and other project policies please see lfprojects.org/policies/.