Documentation Index
Fetch the complete documentation index at: https://mintlify.com/opensandbox-group/OpenSandbox/llms.txt
Use this file to discover all available pages before exploring further.
The OpenSandbox Go SDK is a client library for the full OpenSandbox API surface, organized around three focused clients: LifecycleClient for creating and managing sandbox instances, ExecdClient for executing commands and managing files inside sandboxes, and EgressClient for inspecting and mutating network policy at runtime. Streaming methods accept an EventHandler callback so you can process output incrementally without buffering.
Installation
Requires Go 1.20 or later.
go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
Quick Start
Create and Manage a Sandbox
package main
import (
"context"
"fmt"
"log"
"github.com/alibaba/OpenSandbox/sdks/sandbox/go"
)
func main() {
ctx := context.Background()
lc := opensandbox.NewLifecycleClient("http://localhost:8080/v1", "your-api-key")
sbx, err := lc.CreateSandbox(ctx, opensandbox.CreateSandboxRequest{
Image: opensandbox.ImageSpec{URI: "python:3.12"},
Entrypoint: []string{"/bin/sh"},
ResourceLimits: opensandbox.ResourceLimits{
"cpu": "500m",
"memory": "512Mi",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Created sandbox: %s (state: %s)\n", sbx.ID, sbx.Status.State)
sbx, err = lc.GetSandbox(ctx, sbx.ID)
if err != nil {
log.Fatal(err)
}
list, err := lc.ListSandboxes(ctx, opensandbox.ListOptions{
States: []opensandbox.SandboxState{opensandbox.StateRunning},
PageSize: 10,
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Running sandboxes: %d\n", list.Pagination.TotalItems)
_ = lc.PauseSandbox(ctx, sbx.ID)
_ = lc.ResumeSandbox(ctx, sbx.ID)
_ = lc.DeleteSandbox(ctx, sbx.ID)
}
Run a Command with Streaming Output
exec := opensandbox.NewExecdClient("http://localhost:9090", "your-execd-token")
err := exec.RunCommand(ctx, opensandbox.RunCommandRequest{
Command: "echo 'Hello from sandbox!'",
Timeout: 30000,
}, func(event opensandbox.StreamEvent) error {
switch event.Event {
case "stdout":
fmt.Print(event.Data)
case "stderr":
fmt.Fprintf(os.Stderr, "%s", event.Data)
case "execution_complete":
fmt.Println("\n[done]")
}
return nil
})
Inspect and Patch Egress Policy
egress := opensandbox.NewEgressClient("http://localhost:18080", "your-egress-token")
policy, err := egress.GetPolicy(ctx)
fmt.Printf("Mode: %s, Default: %s\n", policy.Mode, policy.Policy.DefaultAction)
updated, err := egress.PatchPolicy(ctx, []opensandbox.NetworkRule{
{Action: "allow", Target: "api.example.com"},
})
Credential Vault
Create the sandbox with CredentialProxy enabled, then write credentials and bindings through the EgressClient.
config := opensandbox.ConnectionConfig{
Domain: "localhost:8080",
Protocol: "http",
APIKey: "your-api-key",
}
sandbox, err := opensandbox.CreateSandbox(ctx, config, opensandbox.SandboxCreateOptions{
Image: "python:3.11",
NetworkPolicy: &opensandbox.NetworkPolicy{
DefaultAction: "deny",
Egress: []opensandbox.NetworkRule{
{Action: "allow", Target: "api.example.com"},
},
},
CredentialProxy: &opensandbox.CredentialProxyConfig{Enabled: true},
})
if err != nil {
return err
}
_, err = sandbox.CreateCredentialVault(ctx, opensandbox.CredentialVaultCreateRequest{
Credentials: []opensandbox.Credential{
{
Name: "api-token",
Source: opensandbox.InlineCredentialSource{
Type: opensandbox.CredentialSourceInline,
Value: "<token>",
},
},
},
Bindings: []opensandbox.CredentialBinding{
{
Name: "api-token",
Match: opensandbox.CredentialMatch{
Schemes: []opensandbox.CredentialScheme{opensandbox.CredentialSchemeHTTPS},
Ports: []int{443},
Hosts: []string{"api.example.com"},
Paths: []string{"/v1/*"},
},
Auth: opensandbox.CredentialAuth{
Type: opensandbox.CredentialAuthAPIKey,
Name: "x-api-key",
Credential: "api-token",
},
},
},
})
Client Options
All three client constructors accept optional Option functions for customizing the underlying HTTP client and timeout.
// Provide a custom HTTP client
lc := opensandbox.NewLifecycleClient(url, key,
opensandbox.WithHTTPClient(myHTTPClient),
)
// Override the default request timeout
exec := opensandbox.NewExecdClient(url, token,
opensandbox.WithTimeout(60 * time.Second),
)
SDK-created HTTP clients enforce NIST 2030 minimum TLS certificate strength by default (RSA ≥ 2048, EC ≥ 224, hash ≥ 224). To interoperate with legacy endpoints, set AllowWeakServerCertKeyLengths: true in TransportConfig.
API Reference
LifecycleClient
Created with NewLifecycleClient(baseURL, apiKey string, opts ...Option).
| Method | Description |
|---|
CreateSandbox(ctx, req) | Create a new sandbox from a container image |
GetSandbox(ctx, id) | Get sandbox details by ID |
ListSandboxes(ctx, opts) | List sandboxes with filtering and pagination |
DeleteSandbox(ctx, id) | Delete a sandbox |
PauseSandbox(ctx, id) | Pause a running sandbox |
ResumeSandbox(ctx, id) | Resume a paused sandbox |
RenewExpiration(ctx, id, expiresAt) | Extend sandbox expiration time |
GetEndpoint(ctx, sandboxID, port, useServerProxy) | Get public endpoint for a sandbox port |
GetSignedEndpoint(ctx, sandboxID, port, expires) | Get signed endpoint URL with OSEP-0011 route token |
ExecdClient
Created with NewExecdClient(baseURL, accessToken string, opts ...Option).
Commands
Files
Code Execution
Metrics
| Method | Description |
|---|
RunCommand(ctx, req, handler) | Run a command with SSE streaming |
CreateSession(ctx) | Create a bash session |
RunInSession(ctx, sessionID, req, handler) | Run command in session with SSE |
DeleteSession(ctx, sessionID) | Delete a bash session |
InterruptCommand(ctx, sessionID) | Interrupt a running command |
GetCommandStatus(ctx, commandID) | Get command execution status |
GetCommandLogs(ctx, commandID, cursor) | Get command stdout/stderr |
| Method | Description |
|---|
UploadFile(ctx, file, opts) | Upload a file to the sandbox |
UploadFiles(ctx, entries) | Upload multiple files to the sandbox |
DownloadFile(ctx, remotePath, rangeHeader) | Download a file from the sandbox |
GetFileInfo(ctx, path) | Get file metadata |
DeleteFiles(ctx, paths) | Delete files |
SearchFiles(ctx, dir, pattern) | Search files by glob pattern |
ListDirectory(ctx, path) | List directory contents |
ListDirectoryWithDepth(ctx, path, depth) | List directory contents up to depth |
MoveFiles(ctx, req) | Move or rename files |
SetPermissions(ctx, req) | Change file permissions |
ReplaceInFiles(ctx, req) | Text replacement in files |
CreateDirectory(ctx, path, mode) | Create a directory (mkdir -p) |
DeleteDirectory(ctx, path) | Delete a directory recursively |
| Method | Description |
|---|
ExecuteCode(ctx, req, handler) | Execute code with SSE streaming |
ListContexts(ctx, language) | List active code execution contexts |
CreateContext(ctx, req) | Create a code execution context |
GetContext(ctx, contextID) | Get context details |
DeleteContext(ctx, contextID) | Delete a context |
DeleteContextsByLanguage(ctx, language) | Delete all contexts for a language |
InterruptCode(ctx, sessionID) | Interrupt running code |
| Method | Description |
|---|
GetMetrics(ctx) | Get system resource metrics |
WatchMetrics(ctx, handler) | Stream metrics via SSE |
Ping(ctx) | Check server health |
EgressClient
Created with NewEgressClient(baseURL, authToken string, opts ...Option).
| Method | Description |
|---|
GetPolicy(ctx) | Get current egress policy |
PatchPolicy(ctx, rules) | Merge rules into current policy |
CreateCredentialVault(ctx, req) | Create sandbox-local Credential Vault state |
GetCredentialVault(ctx) | Get sanitized Credential Vault state |
PatchCredentialVault(ctx, req) | Atomically mutate credentials and bindings |
DeleteCredentialVault(ctx) | Delete sandbox-local Credential Vault state |
ListCredentialVaultCredentials(ctx) | List sanitized credential metadata |
GetCredentialVaultCredential(ctx, name) | Get sanitized metadata for one credential |
GetCredentialVaultBinding(ctx, name) | Get sanitized metadata for one binding |
SSE Streaming
Methods that stream output (RunCommand, ExecuteCode, RunInSession, WatchMetrics) accept an EventHandler callback:
type EventHandler func(event StreamEvent) error
StreamEvent contains:
Event — event type (e.g. "stdout", "stderr", "result", "execution_complete")Data — raw event payload (JSON string for NDJSON streams)ID — optional event identifier
Return a non-nil error from the handler to stop processing the stream early.
Error Handling
Non-2xx responses are returned as *opensandbox.APIError:
_, err := lc.GetSandbox(ctx, "nonexistent")
if apiErr, ok := err.(*opensandbox.APIError); ok {
fmt.Printf("HTTP %d: %s — %s\n", apiErr.StatusCode, apiErr.Response.Code, apiErr.Response.Message)
}
