Sandboxes: add a Docker Engine setup example for custom v3 workloads #26391

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

I can't find what I'm looking for

Description

The v3 custom-workload tutorial shows how to build an agent environment from a Linux base image, but does not explain how to enable Docker Engine inside that workload so the agent can build images and run containers or Compose applications.

The example uses UBI and installs the agent and supporting packages without showing Docker installation or daemon startup. The base-image guide mentions Docker CLI tooling, while the capability reference describes privileged@1 support. These pieces do not give a reader a complete answer to whether installing Docker is sufficient, what starts the daemon, what privileges and storage are required, or how to verify the result.

The distinction matters: microVM isolation does not by itself tell a kit author which tools and services their custom workload image includes. Likewise, the presence of the Docker CLI does not demonstrate that an Engine is available and running.

Location

• https://docs.docker.com/ai/sandboxes/customize/author/build-an-agent/
• https://docs.docker.com/ai/sandboxes/customize/author/base-images/
• https://docs.docker.com/ai/sandboxes/customize/author/capabilities/

Suggestion

Add a tested end-to-end example for a Docker-enabled v3 workload, linked from the custom-workload tutorial and base-image guide. Cover:

1. A suitable base image, or the packages needed when using a custom Linux image, distinguishing Docker CLI, Engine, Buildx, and Compose as appropriate.
2. The required v3 capability declarations, privileges, daemon startup mechanism, and how the agent user connects to the Engine.
3. Storage and persistence for Docker images, containers, and volumes, including what happens when the sandbox is restarted or removed.
4. A minimal Dockerfile and kit descriptor with the exact command used to launch the workload.
5. Verification with docker version or docker info and a small build/run example, plus troubleshooting for an unavailable daemon.
6. The minimum supported sbx version and local/cloud restrictions. The capability table currently lists local privileged@1 support from v0.48.0 and no cloud support; make the example's scope explicit and describe a cloud alternative only if one is supported.

Prefer a complete, maintained example over an assumption that every custom workload automatically includes a running Docker Engine. Link the general architecture explanation to the concrete setup requirements.