Docker Sandboxes
The Docker Sandboxes provider runs each Devsy machine in a local sbx microVM. Devsy uses the private Docker Engine inside the VM for devcontainers, including Compose. A host Docker Engine is not required.
Requirements and installation
Install the standalone sbx CLI and sign in using Docker's instructions. Configure Docker Sandboxes network policy separately. Install a compatible Devsy core release.
The v0.1.1 prerelease requires Devsy v1.27.0-beta.4 and contains a macOS arm64 binary. Install it explicitly while there is no stable provider release:
devsy provider add https://github.com/devsy-org/devsy-provider-docker-sandbox/releases/download/v0.1.1/provider.yaml
devsy workspace up https://github.com/microsoft/vscode-remote-try-node --provider docker-sandboxA successful add makes Docker Sandboxes the default for the current context. To restore the previous default, run devsy provider use <previous-name>.
Once a stable provider release is available, use devsy provider add docker-sandbox to install the latest stable release. Check its manifest for available hosts.
The current provider source builds for macOS arm64, Linux amd64 and arm64, and Windows amd64. Only macOS arm64 has native VM qualification. The other hosts are built and unit tested only and run with a warning when published. macOS requires Apple silicon and macOS 14 or later. Linux requires Ubuntu 24.04 or later and accessible KVM. Windows requires Windows 11 and Windows Hypervisor Platform. A VM host needs nested virtualization.
The current provider source warns for an unqualified sbx version and proceeds on a best effort basis. Doctor reports the warning too. Check the release documentation for the behavior of the version you install. Undecodable output, an identity mismatch, or a failed guest capacity probe still stops the operation.
Machine resources
Set machine options when creating the machine. SBX_CPUS sets virtual CPUs, SBX_MEMORY sets memory, SBX_ROOT_DISK sets space for the guest system and sources, and SBX_DOCKER_DISK sets space for Docker images, containers, and volumes. Sizes use integer binary m or g units. The defaults are two CPUs, 4g of memory, and 40g for each disk. SBX_PATH can select a different sbx executable. The provider validates these values before creating a VM.
| Option | Default | Purpose |
|---|---|---|
SBX_PATH | sbx | Executable name or absolute path. |
SBX_CPUS | 2 | CPUs, from one to the host logical CPU count. |
SBX_MEMORY | 4g | Guest memory, at least 512m. |
SBX_ROOT_DISK | 40g | Guest root disk, at least 8g. |
SBX_DOCKER_DISK | 40g | Docker data disk, at least 512m. |
Resources cannot be resized in place. Create another machine and deliberately move the data you need before deleting the original. Changing a saved machine option does not destroy and recreate its VM.
Sources and development containers
Git sources are cloned into the guest. Local folder sources are uploaded to the guest, not mounted live from the workstation. A local folder rebuild uploads host files again and can overwrite matching guest edits. Push work to Git or transfer it out of the VM if you need it after machine deletion.
The existing Devsy Docker driver handles Dockerfiles, Features, Compose, image sources, lifecycle commands, named volumes, and ordinary guest Docker mounts. An absolute bind source refers to a path in the guest VM, not a path on your workstation. Devsy runs initializeCommand in the VM. Your devcontainer chooses its own user and shell.
Devsy's SSH tunnel connects to the final devcontainer for terminal, editor, and application forwarding. A port published by the guest Docker Engine is not automatically a workstation port. Use Devsy port forwarding to reach an application from your host.
Network and credentials
Docker Sandboxes network policy still applies to the VM and its containers. The provider does not open blocked destinations or disable TLS verification. Container builds and applications may need project specific proxy variables and CA installation. A project using a forward proxy should add the proxy's public CA to its own build context outside version controlled source, install it in the image trust store before HTTPS commands, and pass the proxy build arguments and runtime variables deliberately. Rebuild after CA rotation. Other base images and applications can use different trust stores.
The guest Docker Engine does not share the host Docker Engine or its socket. Devsy credential forwarding and Docker Sandboxes host integrations are separate authority paths. Check your Devsy context and Docker Sandboxes settings for Git and registry credentials, SSH agent forwarding, MCP integrations, and network access. A mountless VM does not disable those integrations. Private image pulls from the guest Engine and sandbox template pulls use separate credential paths.
Stop, delete, and recovery
Stopping a machine preserves its guest sources, images, containers, and volumes. Starting resumes the same VM. Rebuilding a workspace changes the inner devcontainer without replacing the VM. Deleting a default workspace machine removes the VM and all its guest data, including named volumes. Deleting a workspace on an explicitly shared machine leaves that machine and its other workspaces intact. Uninstalling the provider does not delete its VMs.
With --single-machine, deleting its last workspace deletes the shared VM and all guest data. Back up anything you need before deleting that workspace.
Provider state is stored under your user configuration directory at devsy-provider-docker-sandbox/state-v1. If creation fails, do not remove that directory or manually reuse a sandbox name. The provider reports the exact machine key and any unresolved child attempt or backend operation. A lost VM is never silently recreated in the same machine generation.
A pending context deletion blocks normal commands but does not stop a provider cleanup helper that Devsy already started. Let that helper finish its scoped cleanup before retrying deletion.
After installation, run devsy provider list --result-format=json. If you installed with devsy --home <path>, use devsy --home <path> provider list --result-format=json and treat that path as Devsy's data directory. In config.binaries.DOCKER_SANDBOX_PROVIDER, select the record whose os and arch match your host. An absolute path is the executable. For a remote archive, use archivePath under the data directory at contexts/<context>/providers/<alias>/binaries/docker_sandbox_provider/. Otherwise, use the record's name in that directory. If name is empty, use the base name of path instead. Without a --home override, DEVSY_HOME names the data directory when set. Otherwise Devsy uses ~/.devsy on macOS and Linux, or %LOCALAPPDATA%\devsy on Windows. Use the resolved local executable, not the asset URL.
The provider executable installed with the provider accepts:
<provider-executable> doctor --machine-key <full-key> --json
<provider-executable> recover --machine-key <full-key> --attempt <id> --acknowledge-client-terminated
<provider-executable> recover --machine-key <full-key> --operation <id> --acknowledge-backend-settled
<provider-executable> delete --machine-key <full-key>Use doctor to inspect the saved identity and backend observation without starting a stopped VM. An attempt acknowledgement is appropriate only after its orphaned client has terminated or the host has restarted. A backend acknowledgement is appropriate only after the Docker side operation has settled. Neither acknowledgement starts, stops, or removes a VM. devsy provider delete removes the installed executable. Reinstall the same compatible release or preserve its executable before removal if you need scoped recovery afterward. Use scoped deletion only for a machine you intend to destroy. Never use global sbx reset or prune to recover one machine.