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

Quick Start

This guide walks you through installing the OpenShell Go SDK, connecting to a gateway, creating a sandbox, running a command, and cleaning up. You should be up and running in under 5 minutes.

  • Go 1.25.13 or later
  • Access to an OpenShell gateway (address and authentication token)

Add the SDK to your Go module:

Terminal window
go get github.com/ai-openshell/sdk-go@latest

Create a client by providing the gateway address and authentication credentials:

package main
import (
"context"
"fmt"
"log"
v1 "github.com/ai-openshell/sdk-go/openshell/v1"
)
func main() {
client, err := v1.NewClient(v1.Config{
Address: "gateway.example.com:443",
Auth: v1.StaticToken("my-token"),
})
if err != nil {
log.Fatal(err)
}
defer client.Close()

For production use, load the token from an environment variable instead of hardcoding it: v1.StaticToken(os.Getenv("OPENSHELL_TOKEN"))

The Config struct accepts optional fields for TLS configuration and retry policies. For development against a local gateway without TLS, use v1.NoAuth() and set TLS to skip verification.

Verify the gateway is reachable:

ctx := context.Background()
health, err := client.Health().Check(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Gateway healthy: %v\n", health.Healthy)

Create a sandbox with a Python image:

sandbox, err := client.Sandboxes().Create(ctx, "default", "my-sandbox", &v1.SandboxSpec{
Template: &v1.SandboxTemplate{Image: "python:3.12"},
Environment: map[string]string{"LANG": "en_US.UTF-8"},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created sandbox: %s\n", sandbox.Name)

Sandboxes take a moment to provision. Use WaitReady to block until the sandbox is ready to accept commands:

sandbox, err = client.Sandboxes().WaitReady(ctx, "default", sandbox.Name)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Sandbox is ready (phase: %s)\n", sandbox.Status.Phase)

Execute a command inside the sandbox:

result, err := client.Exec().Run(ctx, "default", sandbox.Name, []string{"echo", "hello from OpenShell"})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Output: %s", result.Stdout)
fmt.Printf("Exit code: %d\n", result.ExitCode)

For long-running commands, use Stream to receive output incrementally, or Interactive for terminal-like sessions.

Delete the sandbox when you are done:

deletion, err := client.Sandboxes().Delete(ctx, "default", sandbox.Name)
if err != nil {
log.Fatal(err)
}
fmt.Printf("Deletion outcome: %v\n", deletion.Outcome)
}

We are a Cloud Native Computing Foundation sandbox project.