[!WARNING] EXPERIMENTAL: The APIs and tools described here are experimental and are not meant for production use.
The gVisor Go SDK (package sandbox) provides a simple API for creating gVisor
sandboxes and executing commands inside them.
To use the SDK, you must have runsc installed on your system. Refer to the
Installation Guide for instructions.
import "gvisor.dev/gvisor/sandboxexec/sandbox"
func New(ctx context.Context, opts ...Option) (*Sandbox, error)
Spawns a new sandbox as a subprocess. The sandbox will be started and running in detached mode.
Parameters:
ctx: Context for the execution.opts: Variadic list of options to configure the sandbox.Returns:
*Sandbox: A pointer to the created Sandbox object.error: An error if the sandbox creation fails.Sandbox represents a running gVisor sandbox.
func (s *Sandbox) Exec(ctx context.Context, cmd string, opts ...string) (stdout string, stderr string, err error)
Runs commands inside the running sandbox as long as the Sandbox is running.
Parameters:
ctx: Context for the execution.cmd: The command to execute (e.g., "uname", "ls").opts: Arguments for the command.Returns:
stdout: Standard output of the command.stderr: Standard error of the command.err: Error if the execution fails.func (s *Sandbox) Close(ctx context.Context) error
Kills the sandbox processes and cleans up the state directory.
Parameters:
ctx: Context for the execution.Returns:
error: An error if cleanup fails.func (s *Sandbox) Bundle() string
Returns the path to the OCI bundle directory for this sandbox.
Option is a function type used to configure a sandbox.
type Option func(*Options)
Options holds the configuration for a Sandbox.
type Options struct {
// Has unexported fields
}
func WithRuntimeDir(runtimeDir string) Option
Sets a custom runtime directory where bundle and state files are written.
func WithID(id string) Option
Sets a specific sandbox ID. If not set, a unique ID will be generated automatically.
func WithNetworking(enabled bool) Option
Configures whether networking is enabled inside the sandbox.
[!IMPORTANT] Enabling networking requires running as root.
For a practical example, see the Quickstart.