diff --git a/sites/docs-devsy-sh/content/docs/managing-providers/docker-sandbox.mdx b/sites/docs-devsy-sh/content/docs/managing-providers/docker-sandbox.mdx index 71074b40e..141cd79a8 100644 --- a/sites/docs-devsy-sh/content/docs/managing-providers/docker-sandbox.mdx +++ b/sites/docs-devsy-sh/content/docs/managing-providers/docker-sandbox.mdx @@ -9,24 +9,35 @@ The Docker Sandboxes provider runs each Devsy machine in a local `sbx` microVM. Install the [standalone `sbx` CLI](https://docs.docker.com/ai/sandboxes/install/) 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: +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: ```sh -devsy provider add https://github.com/devsy-org/devsy-provider-docker-sandbox/releases/download/v0.1.1/provider.yaml +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 ``` -A successful add makes Docker Sandboxes the default for the current context. To restore the previous default, run `devsy provider use `. +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 `. -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 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. -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. +### Hosts -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. +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 versions + +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 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. +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. | Option | Default | Purpose | | --- | --- | --- | @@ -34,7 +45,12 @@ Set machine options when creating the machine. `SBX_CPUS` sets virtual CPUs, `SB | `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`. | +| `SBX_DOCKER_DISK` | `40g` | Docker data disk. See the minimum below. | + +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 "" 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. @@ -73,4 +89,4 @@ The provider executable installed with the provider accepts: delete --machine-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. +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 ` doctor --list`, then run ` delete --machine-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.