Skip to content
OpenShell
These docs are for the development version. Go to the latest released version (0.1.8).

Sandbox Templates

Accessor: client.SandboxTemplates()

Manage reusable, workspace-scoped sandbox workload templates. Templates own the portable workload shape and optional driver-specific config. Sandbox creation can reference a template by name while supplying only governance fields such as providers or policy.

The Go SDK names the reusable resource SandboxWorkloadTemplate because SandboxTemplate already represents the legacy inline compute template inside SandboxSpec.

Creates a reusable template in a workspace.

gpuCount := uint32(1)
template, err := client.SandboxTemplates().Create(ctx, "default", &v1.SandboxWorkloadTemplate{
Name: "gpu-kata",
Labels: map[string]string{
"team": "platform",
},
Spec: v1.SandboxWorkloadTemplateSpec{
Workload: &v1.SandboxWorkloadConfig{
Image: "nvcr.io/nvidia/openshell:latest",
Environment: map[string]string{
"NVIDIA_VISIBLE_DEVICES": "all",
},
Resources: &v1.SandboxResources{
CPU: "2",
Memory: "8Gi",
GPU: &v1.SandboxGPURequirements{Count: &gpuCount},
},
},
DriverConfig: map[string]any{
"kubernetes": map[string]any{
"pod": map[string]any{
"runtime_class_name": "kata",
},
},
},
DesiredServiceLevel: &v1.SandboxServiceLevel{
Startup: &v1.SandboxStartup{
ReadyWithin: 45 * time.Second,
MaxBurst: 2,
},
},
},
})

Set GPU: &v1.SandboxGPURequirements{} to request the active driver’s default GPU assignment without specifying a count.

Use CreateSandboxFromTemplate to create a sandbox from a named reusable template without changing the legacy Sandboxes() interface.

sb, err := client.CreateSandboxFromTemplate(
ctx,
"default",
"training-run",
"gpu-kata",
&v1.SandboxSpec{
Providers: []string{"openai"},
Policy: policy,
},
v1.WithLabels(map[string]string{"job": "training"}),
)

When creating from a template, the spec should only include governance fields: Providers, Policy, Command, and TTY. Workload fields such as image, environment, CPU, memory, GPU, and driver config come from the template.

Retrieves a template by name.

template, err := client.SandboxTemplates().Get(ctx, "default", "gpu-kata")
fmt.Println(template.Spec.Workload.Image)

List returns a lazy pager over matching templates in one workspace or across all workspaces. Use ListAll to follow every continuation token automatically.

templates, err := client.SandboxTemplates().ListAll(ctx, "default", v1.ListOptions{
PageSize: 50,
})
allTemplates, err := client.SandboxTemplates().ListAll(ctx, "", v1.ListOptions{
AllWorkspaces: true,
})

Deletes a template by name. Existing sandboxes created from the template are not deleted.

deletion, err := client.SandboxTemplates().Delete(ctx, "default", "gpu-kata")

The fake client includes the same template sub-client and can be pre-populated for tests.

client := fake.NewClient()
client.AddSandboxTemplate("default", &types.SandboxWorkloadTemplate{
Name: "gpu-kata",
Spec: types.SandboxWorkloadTemplateSpec{
Workload: &types.SandboxWorkloadConfig{Image: "python:3.12"},
},
})

We are a Cloud Native Computing Foundation sandbox project.