mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-11 04:30:53 +08:00
Drew Newberry
9244868056
* docs: refresh architecture and agent guides Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: describe updated security architecture neutrally Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: highlight new isolation primitives Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(sandboxes): clarify how to disconnect Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: align architecture and guides with current navigation Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(extensibility): streamline extension authentication guidance Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Drew Newberry <anewberry@nvidia.com>
127 lines
3.3 KiB
Plaintext
127 lines
3.3 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "Go SDK"
|
|
sidebar-title: "Go"
|
|
description: "Install the OpenShell Go SDK, connect to a gateway, and manage a sandbox."
|
|
keywords: "OpenShell, SDK, Go, Golang, gRPC, Sandbox"
|
|
position: 1
|
|
---
|
|
|
|
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
|
|
|
|
The SDK requires Go 1.25.13 or later. Add it to your Go module:
|
|
|
|
```shell
|
|
go get github.com/NVIDIA/OpenShell/sdk/go@latest
|
|
```
|
|
|
|
## Connect to a Gateway
|
|
|
|
Pass a `host:port` address to `NewClient`. For a local gateway that allows
|
|
unauthenticated plaintext connections:
|
|
|
|
```go
|
|
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:
|
|
|
|
```go
|
|
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
|
|
|
|
Resource methods take an explicit workspace. The following example creates a
|
|
sandbox in `default`, waits for readiness, runs a command, and requests
|
|
deletion:
|
|
|
|
```go
|
|
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
|
|
|
|
- Review [Gateway Authentication](/how-it-works/gateways/authentication) before connecting a service to a production gateway.
|
|
- Review [API Errors](/sdk/api-errors) for the gateway error model.
|
|
- Browse the [Go package reference](https://pkg.go.dev/github.com/NVIDIA/OpenShell/sdk/go/openshell/v1) for all exported types and methods.
|