Configure sandboxes for jobs

Cloud Run sandboxes provide a fast, secure, and isolated environment to execute agent code, perform data transformations, and safely run scripts within your existing job. Sandboxes are highly optimized for latency and run within the same instance as your container, sharing its allocated CPU and memory.

This page describes how to configure sandboxes on your container. For details about writing code to interact with the sandbox using the CLI, see Code execution in Cloud Run.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Install and initialize the gcloud CLI.
  7. Create a Cloud Run job.

Required roles

To get the permissions that you need to configure Cloud Run jobs, ask your administrator to grant you the following IAM roles:

For a list of IAM roles and permissions that are associated with Cloud Run, see Cloud Run IAM roles and Cloud Run IAM permissions. If your Cloud Run job interfaces with Google Cloud APIs, such as Cloud Client Libraries, see the service identity configuration guide. For more information about granting roles, see deployment permissions and manage access.

Enable sandboxes

To enable sandboxes in Cloud Run jobs, use the Google Cloud CLI, a YAML configuration, or Terraform:

gcloud

To create or update the job, specify the --sandbox-launcher flag:

  • To create a job, run the following command:

    gcloud beta run jobs create JOB --image IMAGE_URL --sandbox-launcher

    Replace the following:

    • JOB: the name of your Cloud Run job.
    • IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest
  • To update an existing job, run the following command:

    gcloud beta run jobs update JOB --sandbox-launcher

YAML

  1. If you are creating a new job, skip this step. If you are updating an existing job, download its YAML configuration:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Update your YAML file to include the sandboxLauncher attribute set to true inside your container configuration:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
                sandboxLauncher: true
    

    Replace the following:

    • JOB: the name of your Cloud Run job.
    • CONTAINER: the name of your container.
    • IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest
  3. Create or update the job using the following command:

    gcloud run jobs replace job.yaml

    The gcloud run jobs replace command defaults to using job.yaml file if present.

Terraform

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

Add the following to a google_cloud_run_v2_job resource in your Terraform configuration:
resource "google_cloud_run_v2_job" "default" {
  name     = "JOB"
  location = "REGION"

  template {
    template {
      containers {
        image            = "IMAGE_URL"
        sandbox_launcher = true
      }
    }
  }
}

Replace the following:

  • JOB: the name of your Cloud Run job.
  • REGION: the Google Cloud region. For example, europe-west1.
  • IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest

Sandboxes share the CPU and memory allocated to the host container. Make sure your main container's CPU and memory limits can accommodate both your application and any active sandboxes that you run at the same time.

Disable sandboxes

To disable the ability to launch a sandbox in your job, use the Google Cloud CLI or a YAML configuration:

gcloud

Update the job using the --no-sandbox-launcher flag by running the following command:

gcloud beta run jobs update JOB --no-sandbox-launcher

Replace JOB with the name of your job.

YAML

  1. If you are creating a new job, skip this step. If you are updating an existing job, download its YAML configuration:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Update your YAML file to remove the sandboxLauncher attribute inside your container configuration:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - name: CONTAINER
                image: IMAGE_URL
    

    Replace the following:

    • JOB: the name of your Cloud Run job.
    • CONTAINER: the name of your container.
    • IMAGE_URL: a reference to the container image—for example, us-docker.pkg.dev/cloudrun/container/job:latest
  3. Create or update the job using the following command:

    gcloud run jobs replace job.yaml

    The gcloud run jobs replace command defaults to using job.yaml file if present.

View sandbox settings

To view the current sandbox settings for your Cloud Run job:

Console

  1. In the Google Cloud console, go to the Cloud Run Jobs page:

    Go to Cloud Run jobs

  2. Click the job to open the Job details page.

  3. From the History tab, click the ID of executed job from the list.

  4. In the Containers tab, locate the Sandbox launcher setting to view whether sandboxed containers are enabled or disabled.

gcloud

  1. Use the following command:

    gcloud run jobs executions describe EXECUTION_NAME --format yaml

    Replace EXECUTION_NAME with the name of the job execution.

  2. To verify that sandboxed containers are enabled, locate the sandboxLauncher: true attribute in the returned configuration.

To run untrusted code in a sandbox from your job, see Code execution in Cloud Run.

Configure sandbox templates

Sandbox templates let you define container images for sandboxes. Instead of running sandbox sessions inside your main application container, the sandbox do --template and sandbox run --template commands launch new containers using your specified images, such as Python, Node.js, or a custom execution environment. These sandboxes run in their own containers and share the CPU and memory limits of the main container. You can't set separate CPU and memory limits for a template. Cloud Run supports up to 10 sandbox templates. Volume mounts must reference an in-memory volume on your Cloud Run resource. Sandbox templates provide the following capabilities:

  • Dedicated container images: Declare distinct container images, such as python:3.12-slim or busybox:latest, as sandbox templates. You can also use other runtimes and tools for sandboxes that aren't required on your main container. This keeps your main container lightweight by isolating tools and runtimes used only for sandboxing.

  • On-demand instantiation: The sandbox CLI (/usr/local/gcp/bin/sandbox) spawns new sandbox containers from a template without provisioning new VMs or billing for new instances.

  • Isolated file sharing per sandbox: Share an in-memory volume between your main container and multiple sandboxes while restricting each sandbox to its own isolated subdirectory to prevent sandboxes from viewing or modifying other files.

You can configure sandbox templates using a YAML configuration or the Cloud Run Admin API:

YAML

  1. If you are creating a new job, skip this step. If you are updating an existing job, download its YAML configuration:

    gcloud run jobs describe JOB --format export > job.yaml
  2. Update your job YAML file to include the sandboxes templates configuration:

    apiVersion: run.googleapis.com/v1
    kind: Job
    metadata:
      name: JOB
      annotations:
        run.googleapis.com/launch-stage: BETA
    spec:
      template:
        spec:
          template:
            spec:
              containers:
              - image: IMAGE_URL
                sandboxLauncher: true
                volumeMounts:
                - name: VOLUME_NAME
                  mountPath: CONTAINER_MOUNT_PATH
              volumes:
              - name: VOLUME_NAME
                emptyDir:
                  medium: Memory
              sandboxes:
                templates:
                - name: TEMPLATE_NAME
                  image: TEMPLATE_IMAGE_URL
                  volumeMounts:
                  - name: VOLUME_NAME
                    mountPath: SANDBOX_MOUNT_PATH
                    subPath: SUBPATH
    

    Replace the following:

    • JOB: the name of your Cloud Run job.

    • IMAGE_URL: the container image URL to use for the main container.
    • TEMPLATE_NAME: the name of the template.
    • TEMPLATE_IMAGE_URL: the container image URL to use for the sandbox template.
    • Optional: VOLUME_NAME: the name of the volume to mount.
    • Optional: CONTAINER_MOUNT_PATH: the path where the volume is mounted inside the main container.
    • Optional: SANDBOX_MOUNT_PATH: the path where the volume is mounted inside the sandbox container.
    • Optional: SUBPATH: a relative subdirectory path within the volume to mount into the sandbox container, such as my-subdir. To set a different subdirectory for each sandbox at runtime, use a $(VARIABLE_NAME) placeholder, such as $(SANDBOX_DIR):
      • VARIABLE_NAME can contain only ASCII letters and underscores; digits and hyphens aren't supported.
      • To resolve the placeholder at runtime, pass the --template-var=VARIABLE_NAME=VALUE flag along with --template.
      • subPath doesn't create directories automatically. Create the resolved SUBPATH directory in the volume from the main container, for example using mkdir -p, before running sandbox do or sandbox run.
  3. Create or update the job using the following command:

    gcloud run jobs replace job.yaml

    The gcloud run jobs replace command defaults to using job.yaml file if present.

REST API

To configure sandbox templates, send a PATCH request to the Cloud Run Admin API:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-X PATCH \
"https://run.googleapis.com/v2/projects/PROJECT_ID/locations/REGION/jobs/JOB" \
-d '{
  "launchStage": "BETA",
  "template": {
    "template": {
      "containers": [
        {
          "image": "IMAGE_URL",
          "sandboxLauncher": true,
          "volumeMounts": [
            {
              "name": "VOLUME_NAME",
              "mountPath": "CONTAINER_MOUNT_PATH"
            }
          ]
        }
      ],
      "sandboxes": {
        "templates": [
          {
            "name": "TEMPLATE_NAME",
            "image": "TEMPLATE_IMAGE_URL",
            "volumeMounts": [
              {
                "name": "VOLUME_NAME",
                "mountPath": "SANDBOX_MOUNT_PATH",
                "subPath": "SUBPATH"
              }
            ]
          }
        ]
      },
      "volumes": [
        {
          "name": "VOLUME_NAME",
          "emptyDir": {
            "medium": "MEMORY"
          }
        }
      ]
    }
  }
}'

Replace the following:

  • JOB: the name of your Cloud Run job.

  • PROJECT_ID: your Google Cloud project ID.
  • REGION: the region where your Cloud Run resource is deployed.
  • IMAGE_URL: the container image URL to use for the main container.
  • TEMPLATE_NAME: the name of the template.
  • TEMPLATE_IMAGE_URL: the container image URL to use for the sandbox template.
  • Optional: VOLUME_NAME: the name of the volume to mount.
  • Optional: CONTAINER_MOUNT_PATH: the path where the volume is mounted inside the main container.
  • Optional: SANDBOX_MOUNT_PATH: the path where the volume is mounted inside the sandbox container.
  • Optional: SUBPATH: a relative subdirectory path within the volume to mount into the sandbox container, such as my-subdir. To set a different subdirectory for each sandbox at runtime, use a $(VARIABLE_NAME) placeholder, such as $(SANDBOX_DIR):
    • VARIABLE_NAME can contain only ASCII letters and underscores; digits and hyphens aren't supported.
    • To resolve the placeholder at runtime, pass the --template-var=VARIABLE_NAME=VALUE flag along with --template.
    • subPath doesn't create directories automatically. Create the resolved SUBPATH directory in the volume from the main container, for example using mkdir -p, before running sandbox do or sandbox run.

To run templates using the CLI from within your job container, see Run commands using sandbox templates.