> [!WARNING]
>
> **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](https://docs.cloud.google.com/terms/service-terms#1).
>
> Pre-GA features are available "as is" and might have limited support.
>
> For more information, see the
> [launch stage descriptions](https://cloud.google.com/products/#product-launch-stages).

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](https://docs.cloud.google.com/run/docs/code-execution.md.txt).

## Before you begin

1. [Install and initialize](https://docs.cloud.google.com/sdk/docs.md.txt) the gcloud CLI.
2. Create a Cloud Run [job](https://docs.cloud.google.com/run/docs/create-jobs.md.txt).

## 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](https://docs.cloud.google.com/iam/docs/roles-permissions/run.md.txt#run.developer) (`roles/run.developer`) on the Cloud Run job
- [Service Account User](https://docs.cloud.google.com/iam/docs/roles-permissions/iam.md.txt#iam.serviceAccountUser) (`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](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt)
and [Cloud Run IAM permissions](https://docs.cloud.google.com/run/docs/reference/iam/permissions.md.txt).
If your Cloud Run job interfaces with
Google Cloud APIs, such as Cloud Client Libraries, see the
[service identity configuration guide](https://docs.cloud.google.com/run/docs/configuring/jobs/service-identity.md.txt).
For more information about granting roles, see
[deployment permissions](https://docs.cloud.google.com/run/docs/reference/iam/roles.md.txt#additional-configuration)
and [manage access](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).

## Enable sandboxes

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

### gcloud

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

- To create a job, run the following command:

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

  Replace the following:
  - <var translate="no">JOB</var>: the name of your Cloud Run job.
  - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers.md.txt)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`
- To update an existing job, run the following command:

  ```bash
  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](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt#job):

   ```bash
   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:

   ```yaml
   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:
   - <var translate="no">JOB</var>: the name of your Cloud Run job.
   - <var translate="no">CONTAINER</var>: the name of your container.
   - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers.md.txt)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`
3. Create or update the job using the following command:

   ```bash
   gcloud run jobs replace job.yaml
   ```

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

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:

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

Replace <var translate="no">JOB</var> 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](https://docs.cloud.google.com/run/docs/reference/yaml/v1.md.txt#job):

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

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

   Replace the following:
   - <var translate="no">JOB</var>: the name of your Cloud Run job.
   - <var translate="no">CONTAINER</var>: the name of your container.
   - `IMAGE_URL`: a reference to the [container image](https://docs.cloud.google.com/run/docs/building/containers.md.txt)---for example, `us-docker.pkg.dev/cloudrun/container/job:latest`
3. Create or update the job using the following command:

   ```bash
   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](https://console.cloud.google.com/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:

   ```bash
   gcloud run jobs executions describe EXECUTION_NAME --format yaml
   ```

   Replace <var translate="no">EXECUTION_NAME</var> 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](https://docs.cloud.google.com/run/docs/code-execution.md.txt).