feat(cli): investigate sandbox specs and openshell apply -f #1520

Problem Statement

OpenShell sandbox creation is currently primarily flag-driven through openshell sandbox create. As sandbox configuration grows to include image/source selection, policy, providers, environment, labels, annotations, resource requirements, driver-specific configuration, forwarding, editor integration, and keep/wait behavior, users need a repeatable file format that can be checked into source control, reviewed, and applied consistently from local machines or CI.

This came up during the RFC 0004 review for sandbox resource requirements: #1360 (comment). The concrete user-facing idea is a sandbox config or deployment spec, similar in spirit to a Kubernetes PodSpec or Docker Compose file, consumable with a command like openshell apply -f sandbox.yaml.

Proposed Design

Investigate and propose a first-class OpenShell sandbox definition file consumed by openshell apply -f <file> or an equivalent command, backed by the public SandboxSpec and SandboxTemplate semantics rather than a separate ad hoc model.

The investigation should answer these design questions:

• Manifest shape: likely YAML with versioned metadata such as apiVersion: openshell.ai/v1alpha1, kind: Sandbox, metadata.name, and spec.
• Command semantics: whether apply -f means create only, create-or-update, or a phased model where immutable fields require recreation while mutable policy fields can update a running sandbox.
• CLI parity: how existing sandbox create flags map into manifest fields, including --from, policy, providers, environment, labels, annotations, resource requirements, driver config, forwards, editor, keep, wait, and command arguments.
• Resource model: align with RFC 0004 by using typed portable resource requirements for CPU, memory, GPU, and future resource domains, while keeping backend-specific settings under driver config.
• Validation: perform local schema validation before sending requests, keep gateway-side validation authoritative, and provide clear errors for unsupported or conflicting fields.
• UX: consider --dry-run, --wait, --output, and a future export or scaffold command such as openshell sandbox export <name> or openshell sandbox init.
• Compatibility: define how manifests interact with existing openshell sandbox create workflows and whether this should be introduced as experimental before becoming stable.

The expected output is a concrete design proposal or follow-up implementation issue covering schema, command behavior, tests, and documentation.

Alternatives Considered

• Continue adding flags to openshell sandbox create. This keeps the CLI simple for small cases but does not give users a reviewable, reusable sandbox definition.
• Add JSON blob flags for complex configuration. This is less ergonomic than a structured file and conflicts with RFC 0004 guidance that portable resource requests should stay typed rather than hidden in JSON.
• Reuse Kubernetes PodSpec directly. This is familiar for Kubernetes users but would make OpenShell manifests too Kubernetes-shaped and would not map cleanly to Docker, Podman, VM, or future drivers.
• Add only openshell sandbox create --config <file>. This may be a reasonable implementation step, but the investigation should decide whether the desired long-term model is create-only config or apply-style declarative state.

Agent Investigation

• Used the create-github-issue skill and reviewed the project feature request template.
• Reviewed rfc/README.md; RFCs in review or accepted state are the right place for cross-cutting API and CLI design, while issues can scope the investigation.
• Reviewed RFC 0004 and its PR discussion. The RFC proposes typed portable resource requirements plus driver-specific config, and the review thread explicitly raised a sandbox file spec and openshell apply -f.
• Inspected proto/openshell.proto; SandboxSpec and SandboxTemplate already provide the natural API-backed model for most sandbox manifest fields.
• Inspected crates/openshell-cli/src/run.rs; sandbox create --from currently resolves community sandbox names, image references, local Dockerfiles, and local directories, so manifest semantics need to define source handling deliberately.
• Checked open issues for matching terms such as apply -f, sandbox spec, and deployment spec; no exact duplicate was found.

Checklist

• I have reviewed existing issues and the architecture docs
• This is a design proposal, not a please build this request