Skip to content
OpenShell

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.26 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.