External MicroSandbox Runtime Rollout Decision

Status: fresh Desktop and CLI installs select the published provider; the built-in driver is deprecated. The Microsandbox preset and devsy provider add microsandbox install the latest published external release for a new provider while retaining the name microsandbox. Existing internal providers continue to use the embedded MicroSandbox driver until an explicit source migration. The runtime evidence remains limited to the covered Linux/KVM scenarios.

Current host and runtime contractCopy Anchor Link

Devsy starts a supervised provider process for each runtime operation. It selects the executable from the selected Agent.Binaries entry, requires its SHA-256 declaration, verifies the resolved file and its bytes, then launches it through the Devsy runtime supervisor. The SDK transports protocol messages; it does not download or establish trust in the provider executable. The published provider is trusted host code and runs with the local agent user's authority.

The external provider inherits the host process environment, then receives Devsy's resolved provider/workspace values; this path supplies no separate extra-environment map. This preserves existing provider behavior for settings such as PATH, HOME, proxy configuration, Docker credentials, and temporary directories. The current evidence does not justify an environment allowlist. Provider installation downloads and runtime image downloads are separate from the host's verification of the selected Agent.Binaries executable.

Runtime Protocol v1 uses Info API 1.3 to negotiate recreation-on-run support. Negotiation does not grant permission: Devsy forwards the current operation's explicit recreation permission, and the runtime validates effective configuration before replacing a workspace. This is replacement, not in-place reprovisioning. Failures after replacement starts do not have a general rollback guarantee.

Verified behaviorCopy Anchor Link

PR #1483 established the Linux/KVM parity foundation and is merged. The source-migration acceptance is PR #1487, tested head 0aeea936, implementation run 38628263920. Its exact-head CI completed 88 jobs successfully. The Linux/KVM native catalogue passed 80 cases once: 37 built-in and 43 external. It includes three external-only registry-consumer cases, one remote-agent delivery case, and two existing-workspace source-migration cases. The change is merged at e4286137 after completed Greptile and full CodeRabbit review, including supplemental security/architecture analysis.

The registry cases exercise the published provider against an owned TLS registry and credential helper. They cover successful authenticated access, missing CA refusal, and missing credentials refusal. The remote-agent case checks provider runtime download and workspace-copy reuse when its runtime endpoint returns 404. Its separate Devsy-agent endpoint stays available; this is not an offline-agent guarantee. The source migration cases use the actual provider set-source command on an existing provider named microsandbox, once while its workspace is running and once while stopped. They check provider source and options, workspace association, VM generation, and guest root, volume, and host-bind markers. The running VM keeps its boot ID. The stopped VM remains stopped until ordinary up, then resumes with preserved markers.

The separate Windows provider-update job exercises Go archive and provider-update tests; it is not evidence of a MicroSandbox VM running on Windows. Native provider/VM evidence is Linux/amd64 with KVM only.

Fresh Desktop installationCopy Anchor Link

The Desktop Microsandbox preset and fresh CLI alias select the latest published release from github.com/devsy-org/devsy-provider-microsandbox, while retaining the provider name microsandbox. Users can explicitly select a tag such as @v0.1.8; source-omitted reloads retain an explicit tag. Unpinned GitHub sources resolve the latest release on a later reload, while an existing installation is unchanged until an explicit reload or update. For an already pinned GitHub provider, a Desktop update to a displayed version explicitly selects that version; refreshing without a known target retains the configured pin. The existing Desktop setup path uses provider add ... --use=false; this preserves its current default-provider behavior. CLI --name and --use retain their normal behavior. The explicit compatibility source builtin:microsandbox remains available, as does the embedded manifest for parity tests and compatibility with existing internal provider records.

This choice applies only to a new provider. The wizard refuses an existing provider name before installation; it does not replace or migrate that record. Other presets and custom names retain their behavior. Entering builtin:microsandbox as a custom source deliberately chooses the deprecated built-in provider. Source-omitted reloads of stored internal records retain their legacy meaning; the fresh-install alias does not reinterpret those records. Migrating a stored internal provider to the external runtime requires passing the full external source explicitly to provider set-source. Loading an internal provider refreshes its embedded Exec blocks, not its stored driver or binaries. If initialization fails after a source change is committed, the new source remains selected and the provider records InitError; the command does not promise rollback. The running and stopped migration cases provide evidence for the tested successful transition, not for rollback after arbitrary failures.

Deprecation is reported separately from initialization and default-provider state. It follows the selected built-in driver, including custom-named installations and custom provider manifests. Driver templates use saved provider options; listing does not run option commands to determine the value. An external provider named microsandbox is not deprecated. No compatibility flag, automatic migration or runtime removal is introduced in this deprecation stage; those require their own announced transition and validation.

Evidence and compatibility limitsCopy Anchor Link

Integration and performance fixtures retain explicit release pins for reproducibility; their evidence applies to the tested version, not every future release. The performance artifact from run 38628263920 records one Linux/amd64 hosted run with SDK v1.6.0 and provider v0.1.8. It observed fresh and reused up wall times of 13.504s and 6.335s. Four direct/supervised/supervised/direct probe runs collected one first sample and 100 warm Info and Find samples each; all 808 launches were reaped. The artifact marks cold_cache_measured=false. These are observations, not thresholds, cold-start results, or evidence that supervision improves performance. No process pool is proposed.

Other provider-supported host profiles remain untested here. Upstream requires Apple Silicon on macOS, KVM on Linux, and WHP on Windows; this campaign does not claim runtime parity on those other hosts. The registry tests do not cover every proxy, Docker daemon/context/socket, credential-store, or temp-directory configuration. Neither the built-in driver nor the external provider guarantees removal of every effect after a failed or interrupted create; use a fresh Find and explicit cleanup where recovery is needed. The exact native VM artifacts surviving a particular interruption remain unproven.

The source-migration review and merge gates are complete. Fresh installation and deprecation preserve these platform, performance, environment, and recovery limits. The explicit compatibility selector, embedded manifest, built-in implementation and built-in parity fixture remain available for existing records and deliberate compatibility installs.