Google Cloud VMs

Run every unit on a fresh Compute Engine VM. This is ALE's supported production path for broad snapshot coverage and elastic batch concurrency.

What the provider manages

The gcloud provider selects the image, machine type, GPU, and candidate zones from the task snapshot and environment profile. It creates a VM, waits for the in-guest CUA server, runs one unit, then deletes, stops, or keeps the VM according to cleanup_mode.

• Ubuntu and Windows images are supported.
• GPU snapshots use an L4 virtual workstation accelerator and retry across configured zones when capacity is unavailable.
• CPU tasks use the task-card machine type, with a C-family to N2 fallback when applicable.
• Windows snapshots apply the configured desktop resolution before the run starts.

Understand the two credentials

Before you begin

• A Google Cloud account and billing-enabled project.
• The Google Cloud CLI installed on the ALE host.
• Compute Engine and Cloud Storage APIs enabled.
• Sufficient CPU, GPU, and regional quota for your intended concurrency.

Google Cloud's Free Trial terms and available products can change. Review the current Free Cloud features before relying on credits. Google documents Windows Server VMs as outside the Free Trial, so plan on a paid billing account for Windows benchmark runs.

1. Authenticate and create a project

gcloud auth login

export GCP_PROJECT="ale-$(whoami)"          # must be globally unique
export GCP_REGION="us-central1"
export GCP_SA_NAME="ale-runner"
export GCP_SA_EMAIL="${GCP_SA_NAME}@${GCP_PROJECT}.iam.gserviceaccount.com"
export GCP_BUCKET="${GCP_PROJECT}-ale-results"

gcloud projects create "$GCP_PROJECT" --name="ALE"
gcloud config set project "$GCP_PROJECT"

gcloud billing accounts list
read -p "Billing account ID: " BILLING_ID
gcloud billing projects link "$GCP_PROJECT" --billing-account="$BILLING_ID"

gcloud services enable compute.googleapis.com storage.googleapis.com

2. Create the guest storage identity

gcloud iam service-accounts create "$GCP_SA_NAME" \
  --display-name="ALE storage access"

for role in storage.objectViewer serviceusage.serviceUsageConsumer; do
  gcloud projects add-iam-policy-binding "$GCP_PROJECT" \
    --member="serviceAccount:$GCP_SA_EMAIL" \
    --role="roles/$role" \
    --condition=None
done

mkdir -p secret
gcloud iam service-accounts keys create secret/gcp_key.json \
  --iam-account="$GCP_SA_EMAIL"

Keep this JSON file out of version control. ALE injects it only when an environment config sets gcs_sa_key.

3. Copy the sandbox images

ALE publishes prebaked Ubuntu and Windows images. Copy them into your project once so every run boots from an image you control:

for image in ale-ubuntu22 ale-win10; do
  gcloud compute images create "$image" \
    --source-image="$image" \
    --source-image-project=agenthle-488519
done

4. Create a restricted network rule

ALE connects directly to the CUA server on TCP port 5000. Restrict ingress to the public CIDR of the machine running ALE. Do not expose the control server to the entire internet.

export ALE_CLIENT_CIDR="203.0.113.10/32"   # replace with the ALE host's public IP/CIDR

gcloud compute networks create ale-vpc --subnet-mode=auto
gcloud compute firewall-rules create ale-allow-cua \
  --network=ale-vpc \
  --direction=INGRESS \
  --allow=tcp:5000 \
  --source-ranges="$ALE_CLIENT_CIDR" \
  --target-tags=ale-run

The provider tags every managed VM with ale-run. If the ALE host's public IP changes, update the firewall rule before the next run. See Google Cloud's VPC firewall documentation for alternative network designs.

5. Create a results bucket

This step is optional when output_path: local. It is recommended for large batch artifacts:

gcloud storage buckets create "gs://$GCP_BUCKET" \
  --project="$GCP_PROJECT" \
  --location="$GCP_REGION" \
  --uniform-bucket-level-access

gcloud storage buckets add-iam-policy-binding "gs://$GCP_BUCKET" \
  --member="serviceAccount:$GCP_SA_EMAIL" \
  --role="roles/storage.objectAdmin"

6. Configure ALE

Add the project and key path to secret/.env:

GCP_PROJECT=<your-project-id>
GCP_SA_KEY=secret/gcp_key.json

The shipped configs/environments/environment_gcloud.yaml maps all five task snapshots to Google Cloud. Start with the shipped example_exp.yaml (a demo/hello smoke), then use selected_tasks/unlicensed.txt for the public unlicensed set. Licensed tasks require separately activated software.

Capacity and cleanup

GPU capacity is volatile, so the shipped profile lists several fallback zones. Your project still needs quota in the selected regions. Set concurrency below your CPU, GPU, external-IP, and LLM limits.

Use cleanup_mode: delete for batch runs. If the host process is terminated before cleanup completes, inspect leftovers by tag:

gcloud compute instances list --filter="tags.items=ale-run"