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
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- Install and initialize the gcloud CLI.
- 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:
- Cloud Run Developer (
roles/run.developer) on the Cloud Run job - Service Account User (
roles/iam.serviceAccountUser) on the service identity
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
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
Update your YAML file to include the
sandboxLauncherattribute set totrueinside 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: trueReplace 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
Create or update the job using the following command:
gcloud run jobs replace job.yaml
The
gcloud run jobs replacecommand defaults to usingjob.yamlfile if present.
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
Add the following to agoogle_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
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
Update your YAML file to remove the
sandboxLauncherattribute inside your container configuration:apiVersion: run.googleapis.com/v1 kind: Job metadata: name: JOB spec: template: spec: template: spec: containers: - name: CONTAINER image: IMAGE_URLReplace 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
Create or update the job using the following command:
gcloud run jobs replace job.yaml
The
gcloud run jobs replacecommand defaults to usingjob.yamlfile if present.
View sandbox settings
To view the current sandbox settings for your Cloud Run job:
Console
In the Google Cloud console, go to the Cloud Run Jobs page:
Click the job to open the Job details page.
From the History tab, click the ID of executed job from the list.
In the Containers tab, locate the Sandbox launcher setting to view whether sandboxed containers are enabled or disabled.
gcloud
Use the following command:
gcloud run jobs executions describe EXECUTION_NAME --format yaml
Replace EXECUTION_NAME with the name of the job execution.
To verify that sandboxed containers are enabled, locate the
sandboxLauncher: trueattribute 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-slimorbusybox: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
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
Update your job YAML file to include the
sandboxestemplates 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: SUBPATHReplace 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=VALUEflag along with--template. subPathdoesn't create directories automatically. Create the resolved SUBPATH directory in the volume from the main container, for example usingmkdir -p, before runningsandbox doorsandbox run.
Create or update the job using the following command:
gcloud run jobs replace job.yaml
The
gcloud run jobs replacecommand defaults to usingjob.yamlfile 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=VALUEflag along with--template. subPathdoesn't create directories automatically. Create the resolved SUBPATH directory in the volume from the main container, for example usingmkdir -p, before runningsandbox doorsandbox run.
To run templates using the CLI from within your job container, see Run commands using sandbox templates.