Skip to content

feat(sandbox): add sandbox-initiated supervisor connections with legacy compatibility #4652

Open

Description

@drew

User Story

The requesting OpenShell operator needs the sandbox-initiated connection prerequisite to the shared-supervisor prototype in #4429 to apply across the first-party Sandbox Protocol drivers. Newly provisioned sandboxes should dial their supervisor while existing running sandboxes continue working through upgrade.

Problem Statement

The supervisor currently initiates connections to runtime listeners. Reversing only Kubernetes leaves Docker, Podman, and VM with different connection lifecycles and prevents reviewing the transport prerequisite consistently across drivers.

Proposed Design

Keep the existing TLS/gRPC roles and authenticated Sandbox Protocol, reversing only connection establishment. Kubernetes uses TCP, Docker and Podman use protected Unix sockets without enabling workload networking, and VM guests use vsock to the host supervisor. MXC does not use this Sandbox Protocol connection and requires no transport change. Operator-registered external backends retain their existing endpoint contract.

Preserve legacy transport descriptors. Kubernetes records the generation's direction, treats missing metadata as legacy, and migrates only when both Pods are replaced on stop/start or gateway recovery. Existing Docker containers retain their saved direction through restart; Podman restart metadata defaults to legacy when absent. New VM boots use runtime-initiated vsock. New modes require compatible gateway, supervisor, and runtime binaries; rollback to old binaries after selecting a new mode is unsupported.

Acceptance Criteria

  • New dedicated Kubernetes, Docker, Podman, and VM sandboxes initiate their protected supervisor connection.
  • Running legacy generations are not migrated by reconciliation. Existing Docker and Podman container restarts preserve their direction; Kubernetes generation replacement migrates automatically.
  • Connections authenticate the exact runtime generation and retain supervisor bearer authorization. A connection alone cannot acquire ownership or displace an active session.
  • Docker/Podman socket storage is writable separately from read-only bootstrap credentials; workload networking remains disabled. Kubernetes permits only the paired control flow. VM control uses vsock without a guest NIC.
  • Reconnection retains the current recovery contract, does not replay workload launches or commands, and fails closed on enforcement loss.
  • Existing conformance/E2E paths validate the affected drivers; existing tests receive only necessary fixture updates, with no new unit tests.
  • Crate implementation notes and relevant operator skill guidance describe compatibility and transport behavior.

Suggested UX

Existing create, exec, stop, and start commands remain unchanged. The transport is selected by the driver and requires no workload-policy field or rollout flag.

Alternatives Considered

  • Reversing live connections in place: risks disrupting running workloads.
  • Rewriting the RPC protocol at the same time: expands this prerequisite unnecessarily.
  • Adding TCP networking to Docker/Podman or VM workloads: weakens existing isolation and is unnecessary.

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