Setup

Setup Guide

Help users get their environment ready to run protein design tools.

Quick checklist

Run through this checklist when a user encounters setup issues:

Diagnosing issues

Error: "modal: command not found"

Cause: Modal CLI not installed.

Fix:

pip install modal

Then restart the terminal or run hash -r.

Error: "Permission denied" or "Unauthorized"

Cause: Modal not authenticated.

Fix:

modal setup

This opens a browser. Click "Authorize" to complete authentication.

Error: "No such file or directory: modal_boltzgen.py"

Cause: biomodals repository not cloned or not in correct directory.

Fix:

git clone https://github.com/hgbrian/biomodals
cd biomodals

Error: "uvx: command not found"

Cause: uvx is an optional wrapper from the uv package. It's not required.

Fix: Run modal directly (recommended):

modal run modal_boltzgen.py --help

Or install uv if you prefer using uvx:

pip install uv

Full setup steps

Step 1: Install Modal CLI

pip install modal

Verify: modal --version

Step 2: Authenticate Modal

modal setup

This opens a browser. Click "Authorize".

Verify: modal token show

Step 3: Clone biomodals

git clone https://github.com/hgbrian/biomodals
cd biomodals

Verify: ls modal_*.py should show files like modal_boltzgen.py

Step 4: Test the Setup

cd biomodals
modal run modal_boltzgen.py --help

Expected: Usage instructions appear showing --input-yaml, --protocol, --num-designs options.

Common workflows after setup

Once setup is complete, users can:

cd biomodals

# Design binders with BoltzGen (requires YAML config)
modal run modal_boltzgen.py --input-yaml binder.yaml --protocol protein-anything --num-designs 50

# Generate backbones with RFdiffusion
modal run modal_rfdiffusion.py --pdb target.pdb --contigs "A1-150/0 70-100" --num-designs 100

# Validate with Chai
modal run modal_chai1.py --input-faa designs.fasta

GPU selection

Set GPU with environment variable:

GPU=A10G modal run modal_rfdiffusion.py --pdb target.pdb --contigs "A1-100/0 50-80" --num-designs 10
GPU=L40S modal run modal_boltzgen.py --input-yaml config.yaml --num-designs 50
GPU=A100 modal run modal_chai1.py --input-faa complex.fasta

Modal free tier

Modal offers $30/month in free credits - enough for:

• ~500 BoltzGen designs
• ~2000 RFdiffusion backbones
• ~1000 Chai predictions

Full documentation: See Installation Guide

Inputs

• A fresh environment or a failing runtime with missing dependencies and unclear tooling state.
• The tool the user wants to run first, such as BoltzGen, RFdiffusion, or Chai.
• Information about whether execution will happen locally or through Modal.

Outputs

• A validated environment checklist covering Modal, biomodals, credentials, and test commands.
• A list of missing dependencies or broken paths that must be fixed before design work starts.
• A known-good starting point for the rest of the skill library.

Next Step

After setup passes, move into pdb for target preparation or directly into the first design skill you plan to run.