SDKs

OpenSandbox provides five sandbox SDKs for lifecycle management, command execution, file operations, and resource metrics. This site follows the repository's default branch; a feature merged here may require a newer package than the one you have installed. Check the release index when upgrading.

Installation

Language	Package	Install
Python	opensandbox	pip install opensandbox
JavaScript/TypeScript	@alibaba-group/opensandbox	npm install @alibaba-group/opensandbox
Kotlin/Java	com.alibaba.opensandbox:sandbox	Gradle/Maven
Go	github.com/alibaba/OpenSandbox/sdks/sandbox/go	go get github.com/alibaba/OpenSandbox/sdks/sandbox/go
C#/.NET	Alibaba.OpenSandbox	dotnet add package Alibaba.OpenSandbox

Capability coverage

“Yes” means a public SDK entry point exists. Availability also depends on the server runtime and the execd version installed in the sandbox.

Capability	Python async/sync	JavaScript/TypeScript	Kotlin/Java	Go	C#/.NET
Create, connect, renew, pause/resume, kill	Yes	Yes	Yes	Yes	Yes
Snapshots and template management	Yes	Yes	Yes	Yes	Yes
Resource requests, volumes, lifecycle hooks	Yes	Yes	Yes	Yes	Yes
Commands, files, resource metrics	Yes	Yes	Yes	Yes	Yes
Egress policy and Credential Vault	Yes	Yes	Yes	Yes	Yes
Isolated sessions	Yes	Yes	Yes	Yes	Yes
Client Pool, including Redis	Yes	Yes	Yes	Yes	No
Pool warmup tracing	Yes	Yes, fewer attributes	Yes	No	No
Remote diagnostic logs/events	Yes	No	Yes	No	No
Create-latency telemetry	Yes	Yes	Yes	Yes	Yes

Differences that affect application code

• Pools: Go exposes different warmup controls; the fields accepted by the default pool creator also differ across languages. See the pool configuration matrix.
• Go command control: interrupt, command status, and accumulated command logs are exposed by ExecdClient, rather than the high-level Sandbox wrapper. Neither Sandbox.CreateSession nor ExecdClient.CreateSession accepts an initial working directory. Set Cwd when running a command in the session instead.
• Go connect/resume readiness: pass ReadyOptions to request readiness checks. Without it, connecting resolves the endpoint without checking sandbox health.
• Metrics streaming: Go exposes ExecdClient.WatchMetrics; the other SDKs' stable metrics services provide point-in-time reads. The CLI also has a metrics stream via osb sandbox metrics --watch.
• Timeout units: use Python timedelta and JVM Duration; JavaScript and C# command timeouts use seconds. Go RunCommandRequest.Timeout uses milliseconds.

Template-backed sandboxes require an explicit TTL and inherit their workload configuration from the published template. Their egress policy is managed through the lifecycle API; they do not have a sandbox-side Credential Vault.

Feature guides

• Client Pool: keep a ready buffer, select an acquire policy, share state through Redis, and retire a pool namespace.
• Observability: configure pool warmup traces and creation metrics, understand the default settings, and locate slow startup phases.

Diagnostics

Python and Kotlin/Java expose remote logs/events on both Sandbox and SandboxManager. Use a manager when execd is not ready. Python methods are get_diagnostic_logs / get_diagnostic_events; JVM methods are getDiagnosticLogs / getDiagnosticEvents. Pass a sandbox ID to manager methods and an explicit scope such as container for logs or runtime for events.

JavaScript, Go, and C# can use the CLI or HTTP API. C# SdkDiagnosticsOptions controls local SDK logging. See the API reference for supported scopes and inline/URL delivery.

Lifecycle and cleanup

High-level image/snapshot creation defaults to a 10-minute TTL. Configure the TTL explicitly for your workload. To disable expiration, use Python timeout=None, JavaScript timeoutSeconds: null, Kotlin timeout(null), or the Go/C# ManualCleanup option. Template creation requires a TTL.

close(), DisposeAsync(), and context-manager exit release local client resources; they do not kill the remote sandbox. Kill it in a finally/defer block, or use Python's destroy() helper. Pool acquisitions are consumed once and are not returned to the idle buffer.

CLI

Use the CLI to manage sandboxes, run commands, and work with files from a terminal.

uv tool install opensandbox-cli

MCP server

The MCP server exposes sandbox operations to MCP-capable clients:

pip install opensandbox-mcp