API Overview

The OpenShell Go SDK exposes 12 interfaces through the sub-client pattern. You access each interface through a typed accessor on the Client.

Interface Summary

Interface	Accessor	Description
SandboxInterface	`client.Sandboxes()`	Create, manage, and watch sandbox lifecycle
ExecInterface	`client.Exec()`	Run commands, stream output, interactive sessions
ProviderInterface	`client.Providers()`	Manage compute providers and their lifecycle
ServiceInterface	`client.Services()`	Expose and manage HTTP services inside sandboxes
FileInterface	`client.Files()`	Upload and download files to/from sandboxes
HealthInterface	`client.Health()`	Check gateway health status
SSHInterface	`client.SSH()`	Create SSH sessions and tunnels to sandboxes
TCPInterface	`client.TCP()`	Forward TCP connections to sandbox ports
ConfigInterface	`client.Config()`	Read and update sandbox and gateway configuration
PolicyInterface	`client.Policy()`	Manage draft policy recommendations

Package	Entry Point	Description
gateway	`gateway.NewClient(name)`	Read CLI gateway configs and auto-wire clients

These are accessed through client.Providers():

Interface	Accessor	Description
ProfileInterface	`client.Providers().Profiles()`	Manage provider type profiles
RefreshInterface	`client.Providers().Refresh()`	Configure credential refresh strategies

Each interface has a reference page with method signatures and usage examples:

Sandboxes: Create sandboxes, wait for readiness, watch state changes, manage providers, retrieve logs.
Exec: Execute commands with one-shot, streaming, or interactive modes.
Providers: Register and manage compute providers. Includes sub-clients for profiles and credential refresh.
Services: Expose and manage HTTP services inside sandboxes.
Files: Upload and download files to/from sandboxes.
Health: Check gateway health status.
SSH: Create SSH sessions and tunnels to sandboxes.
TCP: Forward TCP connections to sandbox ports.
Config: Read and update sandbox and gateway configuration.
Policy: Manage draft policy recommendations.
Profiles: Manage provider type profiles (via client.Providers().Profiles()).
Refresh: Configure credential refresh strategies (via client.Providers().Refresh()).

All SDK methods follow these conventions:

Every method takes context.Context as its first argument
Methods that can fail return (result, error)
List methods accept variadic option arguments
Errors from the gateway carry a StatusError with a typed code (see Error Handling)