FoldRun is an AI-powered orchestration platform for protein structure prediction on Google Cloud. It provides a conversational interface that manages the entire lifecycle — from sequence input to structural validation — using Gemini and Google Agent Runtime. Supports multiple structure prediction models (AlphaFold2, OpenFold3, Boltz) via a plugin architecture with shared infrastructure.

• Conversational AI: Natural language interface powered by Gemini for submitting, monitoring, and analyzing predictions
• Multi-Model Support: Plugin architecture for AF2, OpenFold3, Boltz — shared databases, independent pipelines
• Automated Execution: Provisions infrastructure and launches pipelines on Agent Platform with optimal compute selection
• Parallel Analysis: Cloud Run jobs calculate structural metrics (pLDDT, PAE) and generate expert biological insights using Gemini
• Interactive Visualization: Web-based 3D structure viewer with confidence coloring and analysis dashboards
• Smart Database Management: YAML-driven downloads via Cloud Batch with GCS-based gap detection — shared databases downloaded once across models

• Agent: Google ADK with up to 30 native Skills (AF2 + OF3 + Boltz-2), deployed to Agent Runtime
• A2A: Agent-to-Agent protocol proxy (Cloud Run) for agent interoperability
• AI: Gemini (via Agent Platform)
• Compute: Agent Platform Pipelines, Cloud Run, Cloud Batch
• Storage: GCS (artifacts/results), Filestore (genetic databases)
• Infrastructure: Terraform, Cloud Build
• Language: Python 3.10+

Tools (install on your workstation):

• Google Cloud CLI with beta component:

  gcloud components install beta --quiet

• Terraform (>= 1.0)
• uv (Python package manager)

GCP Project Requirements:

• A GCP project with billing enabled
• The deploying user needs these IAM roles on the project:
  • roles/owner (simplest — covers all below), OR these granular roles:
  • roles/editor — create resources
  • roles/iam.serviceAccountAdmin — create service accounts
  • roles/resourcemanager.projectIamAdmin — grant IAM roles
  • roles/artifactregistry.admin — create Artifact Registry repos
  • roles/serviceusage.serviceUsageAdmin — enable APIs

Shared VPC Requirements (if bringing your own network): If you are using a Shared VPC (network belongs to a host project), the following service accounts from this project need the Compute Network User (roles/compute.networkUser) role on the host project or specific subnet:

• service-[PROJECT_NUMBER]@gcp-sa-cloudbatch.iam.gserviceaccount.com (Cloud Batch Service Agent)
• service-[PROJECT_NUMBER]@serverless-robot-prod.iam.gserviceaccount.com (Cloud Run Service Agent, needed for Cloud Run Direct VPC egress)

GPU Quota (check before starting):

• AF2 minimum: 1x NVIDIA A100 40GB (L4 no longer auto-selected — slow DWS provisioning)
• AF2 large proteins (>1500 residues): 1x NVIDIA A100 80GB
• OF3 minimum: 1x NVIDIA A100 40GB (no L4 support)
• Boltz-2 minimum: 1x NVIDIA A100 40GB (no L4 support — diffusion model requires ≥40 GB VRAM)
• Check your quota: GPU quota page
• If you need to request quota increases, do it first — approvals can take hours

# Login with your Google account
gcloud auth login

# Set Application Default Credentials (needed by the deploy script)
gcloud auth application-default login

# Set your project
gcloud config set project YOUR_PROJECT_ID

From the applications/foldrun/ directory:

cd applications/foldrun

# Deploy everything — no .env setup needed for fresh installs
./deploy-all.sh YOUR_PROJECT_ID

Note: You do NOT need to create or edit a .env file for deployment. The deploy script and Cloud Build handle all configuration automatically. The .env file is only needed for local development.

The script will:

1. Enable GCP APIs and provision infrastructure (Terraform)
2. Build and deploy containers, viewer, analysis jobs, and agent (Cloud Build)
3. Ask how to set up genomic databases (see below)

Database setup options (the script asks interactively):

Fast setup from a shared GCS bucket (skip the interactive prompt):

GCS_SOURCE_BUCKET=source-project-foldrun-gdbs ./deploy-all.sh YOUR_PROJECT_ID

If someone already has FoldRun deployed and wants to share their databases with you, you can use their bucket as a source to speed up your deployment. This requires provisioning your infrastructure first so the service account exists.

1. Provision your infrastructure:

./deploy-all.sh YOUR_PROJECT_ID --steps infra

2. They grant your project read access to their databases bucket: They run this (replacing THEIR_PROJECT and YOUR_PROJECT_ID):

gcloud storage buckets add-iam-policy-binding gs://THEIR_PROJECT-foldrun-gdbs \
  --member="serviceAccount:batch-compute-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

3. Complete the deployment with the source bucket:

GCS_SOURCE_BUCKET=THEIR_PROJECT-foldrun-gdbs ./deploy-all.sh YOUR_PROJECT_ID

If you are deploying FoldRun into a Shared VPC (where the network belongs to a host project), follow these steps to ensure correct permissions:

1. Create terraform.tfvars: In the applications/foldrun/terraform/ directory, create a terraform.tfvars file with your network details:

network_name           = "your-existing-vpc-name"
subnet_name            = "your-existing-subnet-name"
network_project_id     = "your-host-project-id"
network_project_number = "your-host-project-number"

2. Enable Cloud Run API and Grant Permissions: Enable the Cloud Run API in your service project so that the Cloud Run Service Agent is created:

gcloud services enable run.googleapis.com --project=YOUR_PROJECT_ID

Then, grant the Cloud Run Service Agent the Compute Network User role on the host project or roles/compute.networkUser on the specific subnet and roles/compute.networkViewer on the host project:

gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
  --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
  --role="roles/compute.networkUser"

3. Provision your infrastructure (creates other service accounts): Run the deployment script with only the infra step:

./deploy-all.sh YOUR_PROJECT_ID --steps infra

4. Grant IAM permissions on the Host Project: The previous step created the service account needed for the batch jobs. Now you must grant the Cloud Batch Service Agent the Compute Network User role on the host project or specific subnet.

Ask your host project administrator to run these commands (replacing HOST_PROJECT_ID, SERVICE_PROJECT_ID, and PROJECT_NUMBER):

gcloud compute networks subnets add-iam-policy-binding SUBNET_NAME \
  --region REGION \
  --member="serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbatch.iam.gserviceaccount.com" \
  --role="roles/compute.networkUser" \
  --project HOST_PROJECT_ID

5. Complete the deployment: Now run the deployment script regularly to build containers and deploy the application:

./deploy-all.sh YOUR_PROJECT_ID

./deploy-all.sh YOUR_PROJECT_ID --steps infra    # Only Terraform
./deploy-all.sh YOUR_PROJECT_ID --steps build    # Only Cloud Build (all containers)
./deploy-all.sh YOUR_PROJECT_ID --steps data     # Only database downloads
DOWNLOAD_MODE=full ./deploy-all.sh YOUR_PROJECT_ID  # Full BFD database (~272GB)

Targeted rebuilds — rebuild only what changed (much faster than full build):

# Rebuild just the OF3 container + redeploy agent (~10 min vs ~25 min full build)
./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target of3

# Redeploy agent only — no container rebuilds (~3 min, e.g. after agent code change)
./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target agent

# Rebuild the analysis job
./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target analysis

# Rebuild multiple targets (comma-separated)
./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target of3,viewer

Available --build-target values:

The agent is automatically redeployed whenever any non-analysis target is included.

Pinned model versions — override without editing any files:

# Upgrade OpenFold3 to a newer release
OF3_VERSION=0.4.0 ./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target of3

# Pin AlphaFold2 to a specific git commit
AF2_VERSION=abc123def ./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target af2

# Upgrade Boltz-2
BOLTZ_VERSION=2.3.0 ./deploy-all.sh YOUR_PROJECT_ID --steps build --build-target boltz2

Default versions are defined in deploy-all.sh and match the tested, pinned values in each container's Dockerfile.

# Check all components are healthy
./check-status.sh YOUR_PROJECT_ID

Expected output:

✅ [Terraform] Infrastructure provisioned
✅ [Cloud Run] foldrun-viewer service is deployed and active
✅ [Cloud Run] foldrun-analysis-job is deployed
✅ [Agent Platform] FoldRun Agent Runtime is deployed
✅ [Data] Databases present (12 folders)
   ✅ AF2 core databases (uniref90 etc.)
   ✅ OF3 weights + CCD
   ⚠️  Boltz-2 databases not downloaded (optional)

Open the Agent Runtime playground:

https://console.cloud.google.com/vertex-ai/agents/locations/YOUR_REGION/agent-engines/YOUR_ENGINE_ID/playground?project=YOUR_PROJECT_ID

The engine ID is printed at the end of deploy-all.sh and saved in foldrun-agent/deployment_metadata.json.

Try these prompts:

• "Predict the structure of ubiquitin" (AF2 monomer)
• "Fold this protein with ATP: MQIFVKTLTGKTITL..." (OF3, protein + ligand)
• "Predict a glycoprotein-ligand complex with covalent modifications" (Boltz-2)
• "What's the structure of P69905?" (checks AlphaFold DB first)

Use via Gemini CLI (A2A):

The deploy prints the A2A proxy URL. Create ~/.gemini/agents/foldrun.md:

---
kind: remote
name: FoldRun
description: Protein structure prediction agent
agent_card_url: https://YOUR_A2A_URL/.well-known/agent.json
auth:
  type: google-credentials
---

Then: gemini -a foldrun "Predict the structure of ubiquitin"

Database downloads run as Cloud Batch jobs in the background. Structure predictions will fail until the required databases are available on NFS.

• From GCS restore: ~15 minutes
• From internet: 2-4 hours

Monitor progress:

gcloud batch jobs list --project=YOUR_PROJECT_ID --location=YOUR_REGION

Or check the Cloud Batch console.

cd foldrun-agent
cp .env.example .env   # Edit with your project settings
uv sync
uv run python foldrun_app/cli.py

For adk web (interactive UI):

cd foldrun-agent
uv run adk web foldrun_app

The dominant cost is Filestore (~$770/mo). Current databases (AF2 reduced + OF3) use ~944 GB of the 2.5 TB provisioned, leaving room for the full BFD database (~272 GB) if needed. BASIC_SSD avoids throughput throttling during concurrent database downloads. Terraform ignores capacity changes after provisioning, so you can resize via Console or gcloud without drift. To stop costs, delete the Filestore instance when not in use and re-download databases when needed.

foldrun/
├── foldrun-agent/              # AI Agent (Google ADK)
│   ├── foldrun_app/
│   │   ├── agent.py            # Agent definition (Gemini + Skills)
│   │   ├── core/               # Shared infrastructure (model-agnostic)
│   │   │   ├── base_tool.py    # BaseTool (GCS, Agent Platform, NFS)
│   │   │   ├── config.py       # GCP project, NFS, GCS config
│   │   │   ├── hardware.py     # GPU quota detection
│   │   │   ├── batch.py        # Cloud Batch job submission
│   │   │   ├── download.py     # YAML-driven database downloader
│   │   │   └── model_registry.py
│   │   ├── models/
│   │   │   ├── af2/            # AlphaFold2 plugin
│   │   │   │   ├── config.py   # AF2Config (image, viewer URL, parallelism)
│   │   │   │   ├── base.py     # AF2Tool (GPU tiers: L4/A100/A100_80GB + relax)
│   │   │   │   ├── pipeline/   # KFP: Configure → Data → ParallelFor[Predict → Relax]
│   │   │   │   ├── tools/      # 19 tools (submit, status, analysis, viewer, DB queries)
│   │   │   │   └── utils/      # FASTA validation, pipeline utils
│   │   │   ├── of3/            # OpenFold3 plugin
│   │   │   │   ├── config.py   # OF3Config (image, params path, viewer URL)
│   │   │   │   ├── base.py     # OF3Tool (GPU tiers: A100/A100_80GB, no relax)
│   │   │   │   ├── pipeline/   # KFP: ConfigureSeeds → MSA+templates → ParallelFor[Predict]
│   │   │   │   ├── tools/      # submit (use_templates=True default), analyze, get_results, open_viewer
│   │   │   │   └── utils/      # Input converter (FASTA→OF3 JSON), pipeline utils
│   │   │   └── boltz2/         # Boltz-2 plugin
│   │   │       ├── config.py   # BOLTZ2Config (image, cache path)
│   │   │       ├── base.py     # BOLTZ2Tool (GPU tiers: A100/A100_80GB only)
│   │   │       ├── pipeline/   # KFP: ConfigureSeeds → MSA(protein) → ParallelFor[Predict]
│   │   │       ├── tools/      # submit, analyze, get_results, open_viewer
│   │   │       └── utils/      # Input converter (FASTA→Boltz-2 YAML), pipeline utils
│   │   └── skills/             # ADK FunctionTool wrappers
│   │       ├── job_submission/  # submit_af2_*, submit_of3_prediction, submit_boltz2_prediction
│   │       ├── job_management/  # status, list, details, delete, GPU quota
│   │       ├── results_analysis/ # AF2 + OF3 + Boltz-2 analysis, results retrieval
│   │       ├── visualization/  # AF2 + OF3 + Boltz-2 viewer tools
│   │       └── _tool_registry.py
│   ├── databases.yaml          # Database manifest (all models)
│   ├── scripts/setup_data.py   # CLI for database downloads
│   └── tests/                  # 298 unit tests
├── src/
│   ├── alphafold-components/    # AF2 pipeline container
│   ├── openfold3-components/    # OF3 pipeline container
│   ├── boltz2-components/       # Boltz-2 pipeline container
│   ├── foldrun-viewer/          # Cloud Run web app (AF2 + OF3 + Boltz-2 3D viewer)
│   ├── foldrun-a2a/             # Cloud Run A2A protocol proxy
│   └── foldrun-analysis-job/    # Cloud Run Job (Unified prediction analysis)
├── terraform/                   # Infrastructure as code
├── cloudbuild.yaml              # CI/CD pipeline
├── deploy-all.sh                # One-command deployment
└── check-status.sh              # Deployment health check

                     ┌──────────────────┐
  A2A clients ──→    │  foldrun-a2a     │ ← A2A protocol proxy (Cloud Run)
                     │  (Cloud Run)     │
                     └───────┬──────────┘
                             │ Forwards to
┌──────────────────┐         │
│  foldrun-agent   │ ←───────┘  Conversational AI (Gemini Flash + up to 30 Skills)
│  (Agent Runtime)  │
└───────┬──────────┘
        │ Native tool calls
        ├──→ Agent Platform Pipelines  ← AF2 + OF3 + Boltz-2 structure prediction
        ├──→ Cloud Batch          ← Genetic database downloads
        ├──→ Cloud Run Jobs       ← Parallel analysis (AF2 + OF3 + Boltz-2) + Gemini Pro expert analysis
        └──→ Cloud Run Service    ← Interactive 3D structure viewer (AF2 + OF3 + Boltz-2)

Public tools like ColabFold and AlphaFold Server are great for academic research but don't meet enterprise requirements for drug discovery pipelines:

Bottom line: FoldRun is built for the pharma/biotech use case where proprietary sequences (pre-clinical targets, engineered antibodies, novel drug candidates) must never leave the organization's cloud boundary. Every step — MSA search, structure prediction, analysis — runs within your GCP project on your infrastructure.

All database definitions live in databases.yaml. The downloader is model-aware — shared databases (uniref90, mgnify, etc.) are tagged with multiple models and downloaded once. Installing OF3 after AF2 only downloads the OF3-specific data.

cd foldrun-agent

# Check what's downloaded vs missing (per model)
uv run python scripts/setup_data.py --status

# Preview what would be downloaded for OF3
uv run python scripts/setup_data.py --models of3 --dry-run

# Download OF3 data (skips shared DBs already present from AF2)
uv run python scripts/setup_data.py --models of3

# Download Boltz-2 data (weights + CCD mols, plus shared protein MSA databases)
uv run python scripts/setup_data.py --models boltz

# Download AF2 reduced set
uv run python scripts/setup_data.py --models af2 --mode reduced

# Download everything for all models
uv run python scripts/setup_data.py --models af2,of3,boltz

# Re-download a specific database
uv run python scripts/setup_data.py --db uniref90 --force

# List all available databases
uv run python scripts/setup_data.py --list

/mnt/nfs/foldrun/
  uniref90/              # Shared (AF2, OF3, Boltz-2)
  mgnify/                # Shared (AF2, OF3, Boltz-2)
  pdb_seqres/            # Shared (AF2, OF3) — also used for OF3 template search
  uniprot/               # Shared (AF2, OF3)
  pdb_mmcif/             # Shared (AF2, OF3) — CIF structures for OF3 template featurization
  alphafold2/params/     # AF2 only
  small_bfd/             # AF2 only
  pdb70/                 # AF2 only
  of3/params/            # OF3 only (~2GB weights)
  of3/ccd/               # OF3 only (~500MB Chemical Component Dictionary)
  of3_msas/              # OF3 runtime — per-job MSA + template alignment files (auto-created)
  rfam/                  # OF3 only (RNA MSA via nhmmer)
  rnacentral/            # OF3 only (RNA MSA via nhmmer)
  boltz2/cache/          # Boltz-2 only — boltz2_conf.ckpt, boltz2_aff.ckpt, mols/ (CCD)

Monitor download progress in the Cloud Batch console.

FoldRun defaults to Jackhmmer (CPU-based) for MSA generation. This works out of the box with the downloaded FASTA databases and produces high-quality alignments. For most use cases, this is the right choice.

MMseqs2 GPU-accelerated search is available as an opt-in for AF2 only. It requires a one-time index conversion step (~3-4 hours) but can speed up MSA search significantly for specific workloads.

When to consider MMseqs2:

• Predicting very large proteins (>1000 residues) where Jackhmmer against full BFD takes hours
• Batch screening hundreds of sequences where MSA time dominates
• You're using use_small_bfd=True (MMseqs2 only works with FASTA databases)

When Jackhmmer is fine (most cases):

• Typical proteins (<500 residues) — MSA completes in 15-30 min on CPU
• The GPU predict step is the real bottleneck, not MSA
• You want to avoid the index conversion setup step
• You're using OF3 or Boltz (MMseqs2 not supported for these models)

To enable MMseqs2 for AF2, first build the indexes, then set msa_method='mmseqs2' when submitting predictions. See the agent's help for details.

cd foldrun-agent

# Unit tests (no GCP credentials needed)
uv run pytest tests/unit/ -v

# Integration tests (requires ADC and Gemini API access)
uv run pytest tests/integration/ -v -m integration

Apache 2.0