Skip to content

feat(server): add sandbox templates - #2833

Open
grs wants to merge 9 commits into
NVIDIA:mainfrom
grs:sandbox-templates-nb
Open

feat(server): add sandbox templates#2833
grs wants to merge 9 commits into
NVIDIA:mainfrom
grs:sandbox-templates-nb

Conversation

@grs

@grs grs commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Summary

Introduces reusable sandbox workload templates — workspace-scoped named resources that define a portable workload shape (image, environment, resources, driver config, service-level settings). Workspace admins create templates once; sandbox creation by template name inherits the workload while callers retain control over policy, providers, and labels.

This is a non-breaking alternative to #2781 that avoids tyign in the cleanup suggested in that PR. This does mean that another name was needed for the message representing sandbox templates, as SandboxTemplate is a inline section of the SandboxSpec. It also means the choice between template name or workload configuration is not explicit in the proto. These are aspects that can be cleanup in a subsequent breaking step when the time is right.

Proto: Four new RPCs (Create/Get/List/Delete SandboxTemplate), SandboxWorkloadTemplate resource with SandboxWorkloadConfig and SandboxResources, workload_template_name on CreateSandboxRequest (field 6),
SandboxWorkloadTemplateProvenance on Sandbox (field 20). No existing field numbers changed or reserved.

Server: Template CRUD handlers with workspace-scoped persistence, workspace deletion blocks on templates, governance/workload split enforcement on create-from-template (rejects inline environment, template,
resource_requirements, log_level), template-to-SandboxSpec resolution, provenance tracking, telemetry for WorkloadTemplate source.

CLI: openshell sandbox template create|get|list|delete subcommands, --template flag on sandbox create with conflicts_with_all against inline workload flags, table/JSON/names-only output formats.

SDKs: Full template CRUD across Rust, Go, Python, and TypeScript SDKs with workspace-scoped and default-workspace surfaces, mock/fake test infrastructure, and docs.

Related Issue

Fixes the sandbox template aspect of (#2680), though not the cleanup which would be treated as part of a wider effort across the proto surface.

Changes

  • Add SandboxWorkloadTemplate proto resource with CRUD RPCs and authorization (admin for write, user for read)
  • Server-side template resolution converts SandboxWorkloadConfig into the existing SandboxSpec/SandboxTemplate shape so compute drivers require no changes
  • CreateSandboxRequest.workload_template_name triggers server-side governance validation and template lookup
  • Created sandboxes carry SandboxWorkloadTemplateProvenance for audit
  • Workspace deletion now blocks on existing templates
  • CLI template subcommands with service-level flags (--ready-within, --max-burst)
  • Rust SDK: curated methods on OpenShellClient and WorkspaceScopedClient, raw proto type aliases
  • Go SDK: SandboxTemplateInterface with domain types, converter layer, fake client
  • Python SDK: SandboxTemplateClient with from_sandbox_client constructor, Sandbox context manager gains template_name
  • TypeScript SDK: SandboxTemplateClient wired into OpenShellClient.sandboxTemplates
  • E2E test covering template create, get, list, and sandbox-create-from-template
  • Published docs updated with template CLI and Python SDK examples

Testing

  • mise run pre-commit passes
  • Unit tests added/updated
  • E2E tests added/updated (if applicable)

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Architecture docs updated (if applicable)

grs added 9 commits August 20, 2026 11:21
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
Signed-off-by: Gordon Sim <gsim@redhat.com>
@grs
grs requested review from a team, derekwaynecarr, mrunalp and sjenning as code owners August 20, 2026 11:00
@copy-pr-bot

copy-pr-bot Bot commented Aug 20, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant