> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actionllama.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Running Agents on Cloud Run Jobs

> Use Google Cloud Run Jobs as an agent execution runtime — scalable, serverless, and pay-per-use

The **Cloud Run Jobs runtime** lets you run agent containers on [Google Cloud Run Jobs](https://cloud.google.com/run/docs/create-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`:

```bash theme={null}
# 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:al-agent-runtime@my-project.iam.gserviceaccount.com" \
    --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

```bash theme={null}
al cred add gcp_service_account
# Paste the contents of ~/al-agent-runtime-key.json when prompted
```

### 3. Create an Artifact Registry repository

```bash theme={null}
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`):

```toml theme={null}
[cloud]
provider = "cloud-run"
project = "my-project"
region = "us-central1"
artifact_registry = "al-agents"
# Optional: service account email for job execution identity
# service_account = "al-agent-runner@my-project.iam.gserviceaccount.com"
```

Also ensure your gateway has a public URL configured:

```toml theme={null}
[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 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](https://cloud.google.com/artifact-registry/docs/repositories/cleanup-policy) 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

| Resource          | Cost                                                           |
| ----------------- | -------------------------------------------------------------- |
| Cloud Run Jobs    | \~$0.00002400 per vCPU-second, ~$0.00000250 per GiB-second     |
| Secret Manager    | $0.06/10,000 API operations; $0.06/active secret version/month |
| Artifact Registry | \~\$0.10/GB/month for stored images                            |
| Cloud Logging     | First 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:

```bash theme={null}
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>`