Skip to content

feat(sandbox): add explicit suspend and resume lifecycle #4763

Open

Description

@drew

User Story

When validating OpenShell sandbox lifecycle through the native V8 example, I need to suspend and resume a running workload without restarting its JavaScript execution, so I can verify retained state and fresh runtime credentials through the OpenShell CLI.

Problem Statement

OpenShell needs an explicit gateway lifecycle for retaining a sandbox workload across suspension, restoring it under a new generation, and reporting unsupported driver semantics consistently.

Impact / Why This Matters

Stopping and starting a sandbox discards live workload state. An explicit suspend/resume workflow lets operators pause a supported workload and continue it later while preserving the gateway authentication and lifecycle boundaries.

Proposed Design

Expose sandbox suspend and resume through the gateway, CLI, and SDKs. Drivers advertise support. Suspension makes a sandbox unavailable while its backend retains the workload; resume creates a new runtime generation and restores it. A strict restore failure preserves the ability to retry. Explicit start, stop, and delete discard retained state.

Use the native V8 example to exercise the workflow with a running JavaScript counter and verify progress across a suspended interval.

Suggested UX

openshell sandbox suspend js-demo
openshell sandbox resume js-demo
openshell sandbox stop js-demo
openshell sandbox start js-demo

Acceptance Criteria

  • Supported sandboxes transition through Suspending and Suspended and resume into a fresh runtime generation.
  • Workload progress continues after resume without replaying initialization.
  • Failed restore launches and startup timeouts preserve retained state for another attempt when restoration remains possible.
  • Explicit start, stop, and delete discard retained state.
  • Unsupported compute drivers reject suspend/resume semantics.
  • CLI and SDK clients expose the new lifecycle operations and phases.
  • Lifecycle tests and the native V8 end-to-end path cover suspend/resume.

Alternatives Considered

Stop/start remains the clean-boot workflow. Durable V8 heap snapshots add a separate cooperative workload contract; this example uses in-memory retention.

Context

Related: #4352 discusses suspension initiated by a backend and supervisor reconnect behavior. This issue covers explicit gateway-driven suspend/resume.

Activity

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions