yao/tai/docs/sandbox.md

Package sandbox

Container lifecycle management. Provides a unified Sandbox interface with three implementations:

Implementation	Constructor	Backend	Mode
Local	NewLocal(addr)	Direct Docker daemon	Local
Docker	NewDocker(addr)	Docker via Tai proxy	Remote
K8s	NewK8s(addr, opts)	Kubernetes via Tai proxy	Remote

Interface

type Sandbox interface {
    Create(ctx context.Context, opts CreateOptions) (id string, err error)
    Start(ctx context.Context, id string) error
    Stop(ctx context.Context, id string, timeout time.Duration) error
    Remove(ctx context.Context, id string, force bool) error
    Exec(ctx context.Context, id string, cmd []string, opts ExecOptions) (*ExecResult, error)
    Inspect(ctx context.Context, id string) (*ContainerInfo, error)
    List(ctx context.Context, opts ListOptions) ([]ContainerInfo, error)
    Close() error
}

Constructors

NewLocal

func NewLocal(addr string) (Sandbox, error)

Connects directly to a Docker daemon. addr can be:

• "" — platform default (Unix socket on Linux/macOS, named pipe on Windows)
• "unix:///var/run/docker.sock" — explicit Unix socket
• "tcp://host:port" — explicit TCP

Pings the daemon on creation; returns an error if unreachable.

NewDocker

func NewDocker(addr string) (Sandbox, error)

Connects to Docker Engine API through Tai's Docker proxy. addr should be "tcp://tai-host:2375".

NewK8s

func NewK8s(addr string, opts ...K8sOption) (Sandbox, error)

Connects to Kubernetes through Tai's TCP proxy. Each sandbox maps to a single-container Pod.

Parameters:

• addr — "host:port" pointing to Tai's K8s proxy endpoint
• opts.KubeConfig — path to kubeconfig file (required). Relative paths are resolved to absolute.
• opts.Namespace — Kubernetes namespace (default "default")

The constructor overrides the kubeconfig's server field to point at addr, enables insecure TLS (since Tai does TCP passthrough), and verifies connectivity by querying the namespace.

All pods created by K8s sandbox are labeled with managed-by: yao-tai-sdk.

Types

CreateOptions

type CreateOptions struct {
    Name       string            // container/pod name
    Image      string            // container image
    Cmd        []string          // entrypoint command
    Env        map[string]string // environment variables
    Binds      []string          // volume binds (Docker only)
    WorkingDir string            // working directory
    Memory     int64             // memory limit in bytes, 0 = no limit
    CPUs       float64           // CPU limit, 0 = no limit
    VNC        bool              // enable VNC port mapping (Local only)
    Ports      []PortMapping     // port mappings (Docker only)
}

PortMapping

type PortMapping struct {
    ContainerPort int    // port inside the container
    HostPort      int    // port on the host, 0 = random
    HostIP        string // host bind address, default "127.0.0.1"
    Protocol      string // "tcp" (default) or "udp"
}

ContainerInfo

type ContainerInfo struct {
    ID     string        // container/pod ID
    Name   string        // container/pod name
    Image  string        // image name
    Status string        // "created", "running", "exited", "removing" (Docker)
                         // "Pending", "Running", "Succeeded", "Failed" (K8s)
    IP     string        // container/pod IP address
    Ports  []PortMapping // mapped ports (Docker only)
}

ExecOptions

type ExecOptions struct {
    WorkDir string            // override working directory
    Env     map[string]string // additional environment variables
}

ExecResult

type ExecResult struct {
    ExitCode int
    Stdout   string
    Stderr   string
}

ListOptions

type ListOptions struct {
    All    bool              // include stopped containers
    Labels map[string]string // filter by labels
}

K8sOption

type K8sOption struct {
    Namespace  string // default "default"
    KubeConfig string // path to kubeconfig file (required)
}

Behavioral Differences

Behavior	Docker (Local/Remote)	K8s
Create returns	container ID (hash)	pod name
Start	starts a stopped container	polls until pod leaves Pending (up to 30s)
Stop	stops with timeout, container persists	deletes the pod with grace period
Remove(force=true)	force-removes	deletes with grace period 0
Exec	Docker exec API	kubectl exec via SPDY
Inspect.Ports	populated from Docker	always empty
List	filters by tai-sdk=true label	filters by managed-by=yao-tai-sdk label
Binds	supported	not supported
VNC flag	auto port-maps 6080 on macOS/Windows	not applicable

Example

sb, _ := sandbox.NewLocal("")
defer sb.Close()

id, _ := sb.Create(ctx, sandbox.CreateOptions{
    Name:  "worker",
    Image: "alpine:latest",
    Cmd:   []string{"sleep", "300"},
    Env:   map[string]string{"FOO": "bar"},
    Memory: 256 * 1024 * 1024, // 256 MB
})

sb.Start(ctx, id)

result, _ := sb.Exec(ctx, id, []string{"echo", "$FOO"}, sandbox.ExecOptions{})
fmt.Println(result.Stdout)

sb.Stop(ctx, id, 10*time.Second)
sb.Remove(ctx, id, false)