Using a Custom Image for a Sandbox

Preparing the Image

Build and push your image to OCI Container Registry in the sandbox's region. Record the full image URI. Grant the sandbox resource principal access to read the repository. If vulnerability scan enforcement applies, provide passing container scan results in the project's compartment.

For example, a dynamic group can select sandbox principals in the compartment containing your project:

ALL {resource.type = 'generativeaisandbox', resource.compartment.id = '<project-compartment-ocid>'}

This rule includes sandbox principals from every project in that compartment. Use the dynamic group's name in the policy:

Allow dynamic-group <sandbox-dynamic-group> to read repos in compartment <repository-compartment-name>

When vulnerability scan enforcement is enabled, also grant the required scan access:

Allow dynamic-group <sandbox-dynamic-group> to read container-scan-results in compartment <project-compartment-name>
Allow dynamic-group <sandbox-dynamic-group> to read vss-family in compartment <project-compartment-name>

See Managing Dynamic Groups.

Creating the Sandbox

Use the full image URI as the runtime value. Replace the image URI with your repository and image reference in the selected region. This example uses Ashburn:

profile_name="DEFAULT"
region="us-ashburn-1"
project_id="PROJECT_OCID"
image_uri="iad.ocir.io/TENANCY_NAMESPACE/REPOSITORY:TAG"

oci --profile "$profile_name" --auth security_token --region "$region" \
  generative-ai-sandbox sandbox create \
  --project-id "$project_id" \
  --display-name custom-image-sandbox \
  --runtime "$image_uri" \
  --shape SMALL \
  --expiration-duration PT1H \
  --wait-for-state RUNNING

After the sandbox reaches RUNNING, run a command supported by your image to verify its runtime. See Running Commands in a Sandbox.

Custom Warm Pools

In the create-project form, select Custom for the warm pool type and enter the image in Container image. The image and configuration must pass validation before the pool becomes active. See Warm Pools for Sandboxes.