Configure sandboxes for services

Preview — Cloud Run sandboxes

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Cloud Run sandboxes provide a fast, secure, and isolated environment to execute untrusted code or run tools, such as AI agents, within your existing service in the second-generation environment. 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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. Install and initialize the gcloud CLI.
2. Deploy a Cloud Run service in the second generation execution environment.

Required roles

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

• Cloud Run Developer (roles/run.developer) on the Cloud Run service
• Service Account User (roles/iam.serviceAccountUser) on the service identity

If you are deploying a service or function from source code, you must also have additional roles granted to you on your project and Cloud Build service account.

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 service 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

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

When you enable sandboxes, your Cloud Run service deploys in the second-generation execution environment. To enable sandboxes in Cloud Run services, use the Google Cloud CLI or a YAML configuration:

gcloud

To deploy or update the service, specify the --sandbox-launcher flag:

• To deploy a new service, run the following command:

  gcloud beta run deploy SERVICE --image IMAGE_URL --sandbox-launcher

  Replace the following:

  • SERVICE: the name of your Cloud Run service.
  • IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

• To update an existing service, run the following command:

  gcloud beta run services update SERVICE --sandbox-launcher

YAML

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

   gcloud run services describe SERVICE --format export > service.yaml

2. Update your service YAML file to include the sandboxLauncher attribute set to true inside your container configuration:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
     annotations:
       run.googleapis.com/launch-stage: BETA
   spec:
     template:
       spec:
         containers:
         - name: CONTAINER
           image: IMAGE_URL
           sandboxLauncher: true
           port: 8080
   

   Replace the following:

   • SERVICE: the name of your Cloud Run service.
   • CONTAINER: the name of your container.
   • IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

3. Create or update the service using the following command:

   gcloud run services replace service.yaml

   The gcloud run services replace command defaults to using service.yaml file if present.

Sandboxes share the CPU and memory allocated to the host container. Make sure your main container limits for CPU and memory are sufficient to accommodate both your application and any active sandboxes you run at the same time.

Disable sandboxes

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

gcloud

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

gcloud beta run services update SERVICE --no-sandbox-launcher

Replace SERVICE with the name of your service.

YAML

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

   gcloud run services describe SERVICE --format export > service.yaml

2. Update your service YAML file to remove the sandboxLauncher attribute inside your container configuration:

   apiVersion: serving.knative.dev/v1
   kind: Service
   metadata:
     name: SERVICE
   spec:
     template:
       spec:
         containers:
         - name: CONTAINER
           image: IMAGE_URL
           port: 8080
   

   Replace the following:

   • SERVICE: the name of your Cloud Run service.
   • CONTAINER: the name of your container.
   • IMAGE_URL: a reference to the container image, for example, us-docker.pkg.dev/cloudrun/container/hello:latest. If you use Artifact Registry, the repository REPO_NAME must already be created. The URL follows the format of LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/PATH:TAG

3. Create or update the service using the following command:

   gcloud run services replace service.yaml

   The gcloud run services replace command defaults to using service.yaml file if present.

Launch sandboxes

Once you enable sandboxes, you can launch sandboxes from within your container execution environment. The sandbox binary is located at /usr/local/gcp/bin/sandbox.

You can execute the binary by referencing its absolute path in your source code. For example, to print Hello inside your isolated sandbox, choose one of the following options:

Node.js

To execute the sandbox command from a Node.js application, include the following code:

exec(`/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"`, (e, stdout, stderr) => {
    res.send({ stdout, stderr });
});

Python

To execute the sandbox command from a Python application, include the following code:

import subprocess
result = subprocess.run(
    ["/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello"],
    capture_output=True,
    text=True,
)
return {"stdout": result.stdout, "stderr": result.stderr}

Go

To execute the sandbox command from a Go application, include the following code:

cmd := exec.Command("/usr/local/gcp/bin/sandbox", "do", "--", "/bin/echo", "Hello")
out, err := cmd.CombinedOutput()

Sandbox CLI

To execute the sandbox command directly from the command line, run the following command:

/usr/local/gcp/bin/sandbox do -- /bin/echo "Hello"

The examples in this guide use the sandbox command instead of its absolute path /usr/local/gcp/bin/sandbox.

To see the complete list of available commands, run the /usr/local/gcp/bin/sandbox -h command.

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