Skip to main content
The Cloud Run Jobs runtime lets you run agent containers on Google Cloud Run Jobs instead of a local Docker daemon or VPS. The scheduler continues to run wherever you host it (local machine, VPS, or CI), while agent execution is offloaded to Cloud Run.

​
Overview

  • Agents run as Cloud Run Jobs — ephemeral, serverless, one job per agent run
  • Credentials via Secret Manager — each credential field is stored as a Secret Manager secret, mounted into the job container at /credentials/<type>/<instance>/<field>
  • Images via Artifact Registry — agent images are pushed to Google Artifact Registry; old tags are automatically pruned
  • Logs via Cloud Logging — structured logs are streamed from Cloud Logging to your scheduler
  • Public gateway required — agents need to reach the gateway for registration, locks, and return values; the gateway URL must be publicly accessible

​
Prerequisites

  • A Google Cloud project with billing enabled
  • The following APIs enabled:
    • run.googleapis.com (Cloud Run)
    • secretmanager.googleapis.com (Secret Manager)
    • artifactregistry.googleapis.com (Artifact Registry)
    • logging.googleapis.com (Cloud Logging)
  • A GCP service account with these roles:
    • roles/run.admin
    • roles/secretmanager.admin
    • roles/artifactregistry.admin
    • roles/logging.viewer
  • An Artifact Registry Docker repository in your project

​
Setup

​
1. Create a service account

In the GCP console or via gcloud: 
# Create the service account
gcloud iam service-accounts create al-agent-runtime \
  --project=my-project \
  --display-name="Action Llama Agent Runtime"

# Grant required roles
for ROLE in run.admin secretmanager.admin artifactregistry.admin logging.viewer; do
  gcloud projects add-iam-policy-binding my-project \
    --member="serviceAccount:[email protected]" \
    --role="roles/$ROLE"
done

# Create and download a key
gcloud iam service-accounts keys create ~/al-agent-runtime-key.json \
  --iam-account=al-agent-runtime@my-project.iam.gserviceaccount.com

​
2. Add the credential to Action Llama

al cred add gcp_service_account
# Paste the contents of ~/al-agent-runtime-key.json when prompted

​
3. Create an Artifact Registry repository

gcloud artifacts repositories create al-agents \
  --repository-format=docker \
  --location=us-central1 \
  --project=my-project

​
4. Configure your environment

Add Cloud Run configuration to your environment file (~/.action-llama/environments/<name>.toml): 
[cloud]
provider = "cloud-run"
project = "my-project"
region = "us-central1"
artifact_registry = "al-agents"
# Optional: service account email for job execution identity
# service_account = "[email protected]"
Also ensure your gateway has a public URL configured: 
[gateway]
url = "https://your-gateway.example.com"

​
How It Works

​
Credential mounting

Before each agent run, the scheduler creates ephemeral Secret Manager secrets — one per credential field. Each secret is mounted into the Cloud Run Job container at /credentials/<type>/<instance>/<field>, preserving the exact path layout that agents expect. After the job completes, the runtime deletes all ephemeral secrets. This is equivalent to the Docker volume mount used by local and VPS runtimes.

​
Image lifecycle

When you run al push or build an agent image:
  1. The image is built locally using docker build
  2. Tagged as <region>-docker.pkg.dev/<project>/<registry>/<image>:<tag>
  3. Pushed to Artifact Registry
  4. Old tags are automatically pruned — only the 3 most recent tags per image are kept
To avoid unbounded storage costs, we recommend also setting up Artifact Registry cleanup policies as an additional safeguard.

​
Job execution

Each agent run:
  1. Creates a Cloud Run Job (al-<agentName>-<runId>)
  2. Runs the job with maxRetries: 0 (one-shot, no automatic retries)
  3. Configures a 1-hour default timeout (configurable via timeout in agent config)
  4. Streams logs from Cloud Logging (with ~5–10s ingestion latency)
  5. Polls for completion every 5 seconds
  6. Deletes the job and its associated secrets after completion

​
Orphan recovery

Cloud Run Jobs are ephemeral. If the scheduler restarts, it can discover running jobs via listRunningAgents(). However, because Cloud Run Jobs don’t expose container environment variables via an inspect API, orphaned jobs are killed rather than re-adopted. This is acceptable for ephemeral workloads.

​
Cost considerations

ResourceCost
Cloud Run Jobs~0.00002400pervCPU−second, 0.00002400 per vCPU-second, ~0.00000250 per GiB-second
Secret Manager0.06/10,000APIoperations;0.06/10,000 API operations; 0.06/active secret version/month
Artifact Registry~$0.10/GB/month for stored images
Cloud LoggingFirst 50 GiB/month free; $0.01/GiB after
For a typical agent run (2 vCPU, 2 GiB RAM, 5 minutes): ~$0.015 in Cloud Run compute.

​
Limitations

  • Agents require a public gateway URL — Cloud Run Jobs run in Google’s infrastructure and can’t reach a purely local scheduler. Configure gateway.url to point to a publicly accessible gateway.
  • No real-time log streaming — Cloud Logging has 5–10s ingestion latency; logs are polled every 3 seconds.
  • No container inspect — orphaned jobs are killed, not re-adopted.
  • Image builds are local — the docker build step runs where the scheduler runs (your machine or VPS). The built image is then pushed to Artifact Registry.
  • Secret Manager quotas — each credential field creates a Secret Manager secret. With many credentials and frequent runs, you may hit the default quota of 9,000 write operations per minute. Request a quota increase if needed.

​
Troubleshooting

Agents can’t reach the gateway Ensure gateway.url in your config points to a publicly reachable URL. The agent container runs in Google Cloud, not on your local network. Secret Manager permission denied The service account needs roles/secretmanager.admin. If you’re using a dedicated execution service account (via service_account in config), that account also needs roles/secretmanager.secretAccessor. Artifact Registry authentication fails Ensure Docker is configured to authenticate with Artifact Registry: 
gcloud auth configure-docker us-central1-docker.pkg.dev
Cloud Run Job creation fails with quota error Check your Cloud Run quotas in the GCP console. The default job limit per region is 1000. Request an increase if needed. Logs appear delayed Cloud Logging has 5–10s ingestion latency. This is expected. For debugging, check logs directly in the GCP console at: https://console.cloud.google.com/run/jobs/details/<region>/<jobId>/executions?project=<project>