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 installationCopy Anchor Link

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 is the only installable release. It requires Devsy v1.27.0-beta.4 and contains a macOS arm64 binary. Install it by URL while there is no stable provider release:

devsy provider add --use=false --name docker-sandbox https://github.com/devsy-org/devsy-provider-docker-sandbox/releases/download/v0.1.1/provider.yaml
devsy provider init docker-sandbox
devsy workspace up https://github.com/microsoft/vscode-remote-try-node --provider docker-sandbox

With --use=false, the add command only installs the provider and keeps your default provider. You must run devsy provider init docker-sandbox before the first workspace, or the workspace command fails because the provider is not initialized. Without --use=false, the add command also initializes the provider and makes it the default for the current context. To restore the previous default, run devsy provider use <previous-name>.

The short form devsy provider add docker-sandbox expands to the devsy-org/devsy-provider-docker-sandbox repository and installs its latest release. GitHub does not count a prerelease as the latest release, so use the URL form until a stable release is published.

HostsCopy Anchor Link

The v0.1.1 manifest contains only a macOS arm64 binary. v0.1.1 accepts only macOS arm64 and fails with E_HOST_UNSUPPORTED on any other host. Builds from the main branch of the provider also build for Linux amd64 and arm64 and Windows amd64. Only macOS arm64 has native VM qualification. On the other hosts a main build runs with a warning, and doctor reports the same warning. No release containing those binaries has been published yet.

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.

sbx versionsCopy Anchor Link

v0.1.1 accepts only sbx v0.50.1, client and daemon, and fails closed on any other version. A failed check reports E_SBX_VERSION, and if sbx cannot be reached it reports E_SBX_UNAVAILABLE. Stop and delete run the same check, so they also fail. If you use v0.1.1, do not update sbx. The sbx release notes list its versions. This guide does not cover installing an older sbx, so keep v0.50.1 installed instead of updating.

Builds from main warn once for an unqualified sbx version and proceed on a best effort basis. doctor reports the same warning. Undecodable output, an identity mismatch, or a failed guest capacity probe still stops the operation in every build.

Builds from main also report E_SBX_DAEMON_RESTART when sbx has been updated and its daemon must be restarted. v0.1.1 has no such error. The provider never restarts the daemon, because a restart stops all running sandboxes. Save your work, run sbx daemon restart in an interactive terminal, and retry. Do not use a daemon restart to fix a v0.1.1 version error.

Machine resourcesCopy Anchor Link

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 are whole numbers followed by a lowercase m or g for binary megabytes or gigabytes, for example 8g or 7680m. Values such as 8G, 8GB or 8192 are rejected. The defaults are two CPUs, 4g of memory, and 40g for each disk. SBX_PATH can select a different sbx executable.

The Docker disk minimum depends on the provider build.

• v0.1.1: The configuration check accepts a Docker disk of 512m or more, and it runs on every command except scoped deletion (delete --machine-key), including stop and ordinary delete. A value below 512m fails with E_CONFIG_DRIFT and size "<value>" below minimum. A value below about 7g passes that check but can fail the guest capacity check when the machine is created. That check requires each guest filesystem to be at least 97 percent of the requested size, and the real filesystem is smaller than requested by an overhead. Measurements on macOS arm64 with sbx v0.50.1 showed a failure at 6g and a pass at 6.5g. The failure is E_GUEST_CAPABILITY. Use 7g or more.
• Builds from main: A Docker disk below 7g, a root disk below 8g or memory below 512m is rejected only when a machine is created, with an error such as size "6g" is below the minimum of 7g. Stop, delete, status and start do not apply the minimums. A malformed size is still rejected on every command except scoped deletion.

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 containersCopy Anchor Link

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 credentialsCopy Anchor Link

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 recoveryCopy Anchor Link

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. It is also the way out of a configuration error (E_CONFIG_DRIFT) on an existing machine that you no longer want. Find the full key with <provider-executable> doctor --list, then run <provider-executable> delete --machine-key <full-key>. In v0.1.1 and in main, the scoped command resolves only SBX_PATH and does not parse the size and CPU options, so an invalid option value does not block it. In v0.1.1 it still runs the sbx version and host checks, so it cannot fix E_SBX_VERSION. Never use global sbx reset or prune to recover one machine.