Create a sandbox from a custom image

Important

This feature is in Beta. To enable this feature preview in the workspace, opt into the Databricks Sandbox setting in the workspace Previews page. See Manage Azure Databricks previews.

You can create a sandbox from your own container image stored in Artifact Registry. Artifact Registry stores container images as governed assets in Unity Catalog, so you control access to them with Unity Catalog privileges. The sandbox starts with the image's packages, tools, and configuration already installed, so you don't need to install dependencies each time you create a sandbox.

For an overview of Databricks Sandbox, see Databricks Sandbox.

Requirements

  • Your workspace meets the Databricks Sandbox prerequisites. See Prerequisites.
  • Your workspace meets the Artifact Registry prerequisites, including enabling the Databricks Artifact Registry preview. See Requirements.
  • You have the USE CATALOG, USE SCHEMA, and READ VOLUME privileges on the catalog and schema that contain the image. See Grant permissions.
  • The image uses glibc 2.25 and above. If the image uses an Ubuntu base, use Ubuntu 18.04 and above. Images that use musl instead of glibc, such as Alpine Linux and images built on it (for example, python:<version>-alpine or node:<version>-alpine), are not supported.

Push an image and create a sandbox

  1. Build the image with Docker and push it to Artifact Registry. See Push an image.

  2. Wait until the image's acceleration status is SUCCESS. Image acceleration runs automatically after you push and can take 15 minutes or more. See Check image acceleration status.

  3. Create the sandbox and set image_uri to the image's Unity Catalog name, in the format catalog.schema.artifact:tag. To pin an exact version, use a digest instead of a tag: catalog.schema.artifact@sha256:<digest>.

    For example, to create a sandbox from the main.agents.agent-base:v1 image, run the following:

    from databricks.sdk import WorkspaceClient
from databricks.sdk.service.sandbox import EnvironmentSpec, Sandbox, SandboxSpec

w = WorkspaceClient()

created = w.sandbox.create_sandbox(
    sandbox=Sandbox(
        spec=SandboxSpec(
            environment=EnvironmentSpec(image_uri="main.agents.agent-base:v1"),
        ),
    ),
    sandbox_id="my-custom-sandbox",
)
print(created.name)   # "sandboxes/my-custom-sandbox"

A sandbox created from a custom image keeps the same persistent home directory and stop and start behavior as any other sandbox.

Troubleshooting

If the create request fails, check the error message:

  • Image <uri> is not ready for use: Image acceleration has not finished. Check the image's acceleration status and retry after it reaches SUCCESS.
  • Not authorized to access image <uri>: You don't have the required privileges on the image. Ask the catalog or schema owner to grant them.

Limitations

  • Custom images must be stored in Artifact Registry. You cannot create a sandbox from an image in an external registry, and Azure Databricks does not build images for you.
  • Sandboxes created from a custom image can take longer to start than sandboxes that use the default environment.

Additional resources

  • Last updated on