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.
Prerequisites
Section titled “Prerequisites”- Go 1.25.13 or later
- Access to an OpenShell gateway (address and authentication token)
Installation
Section titled “Installation”Add the SDK to your Go module:
go get github.com/ai-openshell/sdk-go@latestConnect to the Gateway
Section titled “Connect to the Gateway”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.
Check Gateway Health
Section titled “Check Gateway Health”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
Section titled “Create a Sandbox”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)Wait for the Sandbox to be Ready
Section titled “Wait for the Sandbox to be Ready”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)Run a Command
Section titled “Run a Command”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.
Clean Up
Section titled “Clean Up”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)}Next Steps
Section titled “Next Steps”- Browse the API Overview to see all available interfaces
- Learn about Error Handling for production code
- Set up Testing with the fake client for your test suites
- Explore the Architecture to understand the SDK design
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/.