Skip to content

refactor: specify the boundary and supervisor-registration contracts compute drivers use #5456

Open

Description

@elezar

Part of #5200.

User Story

As an OpenShell Maintainer I want the files and values a compute driver hands to the supervisor to be specified as language-neutral formats, so that drivers can live in other repositories, and be written in other languages, without importing Rust types from core crates.

Problem Statement

A compute driver has two contracts with OpenShell. The first is the ComputeDriver gRPC service in proto/compute_driver.proto, which is already language-neutral. The second is what the driver places inside or beside the sandbox for the supervisor: the runtime descriptor, TLS material, gateway verification keys, bootstrap and authentication files, the listener and transport settings, and the resource claims and paths that go with them.

That second contract is defined only by Rust types. The Docker, Podman, and VM drivers import these from openshell-sandbox-backend (boundary_protocol: BoundaryConfig, BoundaryListener, GatewayVerificationKey, SandboxRuntimeDescriptor, SandboxTlsClientConfig, SandboxTlsServerConfig, SandboxTlsMaterial, SandboxTransport, generate_sandbox_tls_material), from openshell-isolation-interface (ResolvedWorkloadIdentity, ProvisioningEvidence, BackendError), and as constants from the openshell-sandbox-backend root (BACKEND_NAME, GPU_RESOURCE_CLAIM, ALLOW_EXTRA_SUPPLEMENTARY_GROUPS_RESOURCE_CLAIM, SUPERVISOR_CA_RUNTIME_ROOT, SUPERVISOR_CA_RUNTIME_DIR). RFC 0012 defines the descriptor envelope (backend name, version, opaque payload) but leaves the payload and the file formats unspecified.

openshell-sandbox-backend depends on openshell-core, so a driver that imports these types depends on core even after the code in #5383 is split out.

A third contract has no specification either: how a driver registers each sandbox with the gateway's shared supervisor. In-process drivers receive the gateway's SharedSupervision coordinator directly. An out-of-tree driver has no way to reach it, and openshell-supervisor-control types such as SandboxInstanceRegistration and ProxyCaMaterial are Rust-only.

Impact / Why This Matters

  • A driver in another repository must either depend on these crates, which ties it to their versions, or copy the formats from the source, which drifts without a compile error.
  • A driver written in another language cannot be built from the repository's documented contracts.
  • An out-of-tree compute driver built against a pinned checkout of this repository shows the cost. It depends on five crates (openshell-core, openshell-crypto, openshell-isolation-interface, openshell-sandbox-backend, openshell-supervisor-control) and carries a patch set on top of upstream, including a new gateway-initiated bidirectional stream and a capability, openshell.compute.shared-supervision, to reach the shared supervisor.
  • refactor: carve out the driver SDK and container-runtime crate #5383 deliberately leaves isolation_interface, isolation_registration, and boundary_protocol where they are, because moving them into the driver SDK would turn Rust types into the driver-facing API before the formats are agreed.

Proposed Design

Specify each format the driver produces or consumes, as proto messages or documented schemas that live in this repository and are versioned:

  • the runtime descriptor, TLS material, gateway verification keys, bootstrap file, and authentication bundle: field names, encoding, version, location, and permissions;
  • which side produces each one and which side validates it;
  • the resource claims, backend name, and runtime paths that drivers set;
  • the shared-supervision registration a driver performs for each sandbox (launch, withdraw, recovery, supervisor tokens, proxy CA material), including the capability a driver and gateway negotiate for it, with the gateway keeping assignment authority;
  • how this relates to the RFC 0012 BackendDescriptor envelope and to IsolationBackendRegistration in compute_driver.proto.

Validate the formats against more than one kind of driver: a container driver (Docker or Podman), a microVM driver, and the native Windows MXC driver on the windows branch, whose boundary runs as a separate process, connects outward to the host, and uses its own isolation backend name and evidence. The formats should not assume a Linux container, POSIX paths, or a particular connection direction.

Then decide where the Rust types live. They should be generated from, or tested against, the specification. Drivers should no longer need openshell-sandbox-backend or openshell-core.

This issue covers the specification and the decision. Moving the drivers and changing runtime behavior are out of scope.

Acceptance Criteria

  • Every file, value, and constant a driver gives the supervisor is specified in a versioned, language-neutral form in this repository.
  • The shared-supervision registration is specified the same way, and an out-of-tree driver can use it without patching this repository.
  • A conformance test checks the Rust implementation against the specification.
  • The Docker, Podman, and VM drivers can be built without depending on openshell-sandbox-backend or openshell-core.
  • The location of isolation_interface, isolation_registration, and boundary_protocol is decided, and the decision is recorded in refactor: carve out the driver SDK and container-runtime crate #5383's follow-up or in an RFC.
  • Existing Docker, Podman, and VM e2e suites pass without behavior change.

Alternatives Considered

  • Export the Rust types from the driver SDK. Fastest, but turns Rust types into the public contract and ties every driver to Rust.
  • Leave the formats Rust-only and require drivers to depend on the crates. No new specification work, but blocks drivers in other repositories and languages from being independent of core.

Agent Investigation

  • Docker, Podman, and the VM driver all import openshell_sandbox_backend::boundary_protocol and openshell_isolation_interface::contract today. About a dozen items are used in total, and none from runtime, runtime_routed, protobuf, sandbox_auth, or stream_adapter.
  • openshell-sandbox-backend depends on openshell-core for jwt, provider_credentials, net, SandboxSessionId, and generated protos.
  • The in-progress refactor(driver-sdk): carve out the driver SDK and container-runtime crate #5405 keeps these types where they are and splits out the rest of the shared driver code.
  • The out-of-tree driver imports, from core, the compute proto, extension_protocol, the launch-authentication and session types in jwt, SandboxSessionId, resource_admission, sandbox_env, and driver_utils. These are the items refactor(driver-sdk): carve out the driver SDK and container-runtime crate #5405 moves into the SDK. From openshell-sandbox-backend it imports the boundary_protocol types above and runtime_routed::new_route_handle, and from openshell-supervisor-control it imports SandboxInstanceRegistration, ProxyCaMaterial, and SecretPem. It builds one set of inputs into both the guest's BoundaryConfig and the shared supervisor's SandboxRuntimeDescriptor so their claims and evidence digest cannot drift.

Activity

  1. changed the title [-]refactor: specify the boundary formats compute drivers hand to the supervisor[/-] [+]refactor: specify the boundary and supervisor-registration contracts compute drivers use[/+] on Nov 11, 2026
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

    area:gatewayGateway server and control-plane work

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions