Skill v1.0.1

currentLLM-judged scan95/100

adaptyvbio/protein-design-skills/boltzgen

2 files

──Details

PublishedJune 19, 2026 at 11:18 AM

Content Hashsha256:6c504d0a2a98d692...

Git SHA59dd63374314

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 8.1 KB)

SKILL.md8.1 KBactive

SKILL.md · 288 lines · 8.1 KB

version: "1.0.1" name: boltzgen description: > All-atom protein design using BoltzGen diffusion model. Use this skill when: (1) Need side-chain aware design from the start, (2) Designing around small molecules or ligands, (3) Want all-atom diffusion (not just backbone), (4) Require precise binding geometries, (5) Using YAML-based configuration.

For backbone-only generation, use rfdiffusion. For sequence-only design, use proteinmpnn. For structure validation, use boltz. license: MIT category: design-tools tags: [structure-design, sequence-design, diffusion, all-atom, binder] proteinbase_slug: boltzgen proteinbase_url: https://proteinbase.com/design-methods/boltzgen biomodals_script: modal_boltzgen.py

BoltzGen All-Atom Design

Prerequisites

Requirement	Minimum	Recommended
Python	3.11+	3.12
CUDA	12.0+	12.1+
GPU VRAM	24GB	48GB (L40S)
RAM	32GB	64GB

How to run

First time? See Getting started to set up Modal and biomodals.

Option 1: Modal (recommended)

bash

# Clone biomodals
git clone https://github.com/hgbrian/biomodals && cd biomodals
 
# Run BoltzGen (requires YAML config file)
modal run modal_boltzgen.py \
  --input-yaml binder_config.yaml \
  --protocol protein-anything \
  --num-designs 50
 
# With custom GPU
GPU=L40S modal run modal_boltzgen.py \
  --input-yaml binder_config.yaml \
  --protocol protein-anything \
  --num-designs 100

GPU: L40S (48GB) recommended | Timeout: 120min default

Available protocols: protein-anything, peptide-anything, protein-small_molecule, nanobody-anything, antibody-anything

Option 2: Local installation

bash

git clone https://github.com/HannesStark/boltzgen.git
cd boltzgen
pip install boltzgen   # or: pip install -e .
 
# Driven by the boltzgen CLI with a YAML design spec
boltzgen run binder_config.yaml \
  --output out/ \
  --protocol protein-anything \
  --num_designs 50

The first run downloads model weights (~6GB) to ~/.cache. Verify a spec with boltzgen check binder_config.yaml before a full run.

GPU: L40S (48GB) | Time: ~30-60s per design

Key parameters (CLI)

Parameter	Default	Description
`--input-yaml`	required	Path to YAML design specification
`--protocol`	`protein-anything`	Design protocol
`--num-designs`	10	Number of designs to generate
`--steps`	all	Pipeline steps to run (e.g., `design inverse_folding`)

YAML configuration

BoltzGen uses an entity-based YAML format where you specify designed proteins and target structures as entities.

Important notes:

Residue indices use label_seq_id (1-indexed), not author residue numbers
File paths are relative to the YAML file location
Target files should be in CIF format (PDB also works but CIF preferred)
Run boltzgen check config.yaml to verify your specification before running

Basic Binder Config

yaml

entities:
  # Designed protein (variable length 80-140 residues)
  - protein:
      id: B
      sequence: 80..140
 
  # Target from structure file
  - file:
      path: target.cif
      include:
        - chain:
            id: A
      # Specify binding site residues (optional but recommended)
      binding_types:
        - chain:
            id: A
            binding: 45,67,89

Binder with Specific Binding Site

yaml

entities:
  - protein:
      id: G
      sequence: 60..100
 
  - file:
      path: 5cqg.cif
      include:
        - chain:
            id: A
      binding_types:
        - chain:
            id: A
            binding: 343,344,251
      structure_groups: "all"

Peptide Design (Cyclic)

yaml

entities:
  - protein:
      id: S
      sequence: 10..14C6C3  # With cysteines for disulfide
 
  - file:
      path: target.cif
      include:
        - chain:
            id: A
 
constraints:
  - bond:
      atom1: [S, 11, SG]
      atom2: [S, 18, SG]  # Disulfide bond

Design protocols

Protocol	Use Case
`protein-anything`	Design proteins to bind proteins or peptides
`peptide-anything`	Design cyclic peptides to bind proteins
`protein-small_molecule`	Design proteins to bind small molecules
`nanobody-anything`	Design nanobody CDRs
`antibody-anything`	Design antibody CDRs

Output format

output/
├── sample_0/
│   ├── design.cif         # All-atom structure (CIF format)
│   ├── metrics.json       # Confidence scores
│   └── sequence.fasta     # Sequence
├── sample_1/
│   └── ...
└── summary.csv

Note: BoltzGen outputs CIF format. Convert to PDB if needed:

python

from Bio.PDB import MMCIFParser, PDBIO
parser = MMCIFParser()
structure = parser.get_structure("design", "design.cif")
io = PDBIO()
io.set_structure(structure)
io.save("design.pdb")

Sample output

Successful run

$ modal run modal_boltzgen.py --input-yaml binder.yaml --protocol protein-anything --num-designs 10
Running: boltzgen run binder.yaml --output /tmp/out --protocol protein-anything --num_designs 10
[INFO] Loading BoltzGen model...
[INFO] Generating designs...
[INFO] Running inverse folding...
[INFO] Running structure prediction...
[INFO] Filtering and ranking...
[INFO] Pipeline complete
 
Results saved to: ./out/boltzgen/2501161234/

Output directory structure:

out/boltzgen/2501161234/
├── intermediate_designs/           # Raw diffusion outputs
│   ├── design_0.cif
│   └── design_0.npz
├── intermediate_designs_inverse_folded/
│   ├── refold_cif/                 # Refolded complexes
│   └── aggregate_metrics_analyze.csv
└── final_ranked_designs/
    ├── final_10_designs/           # Top designs
    └── results_overview.pdf        # Summary plots

What good output looks like:

Refolding RMSD < 2.0A (design folds as predicted)
ipTM > 0.5 (confident interface)
All designs complete pipeline without errors

Decision tree

Should I use BoltzGen?
│
├─ What type of design?
│  ├─ All-atom precision needed → BoltzGen ✓
│  ├─ Ligand binding pocket → BoltzGen ✓
│  └─ Standard miniprotein → RFdiffusion (faster)
│
├─ What matters most?
│  ├─ Side-chain packing → BoltzGen ✓
│  ├─ Speed / diversity → RFdiffusion
│  ├─ Highest success rate → BindCraft
│  └─ AF2 optimization → ColabDesign
│
└─ Compute resources?
   ├─ Have L40S/A100 (48GB+) → BoltzGen ✓
   └─ Only A10G (24GB) → Consider RFdiffusion

Typical performance

Campaign Size	Time (L40S)	Cost (Modal)	Notes
50 designs	30-45 min	~$8	Quick exploration
100 designs	1-1.5h	~$15	Standard campaign
500 designs	5-8h	~$70	Large campaign

Per-design: ~30-60s for typical binder.

Adaptyv's own tests of these models showed BoltzGen costing about $1.80 per accepted design, averaged across 7 targets (the generation estimates above do not include the extra sampling and refolding needed to reach an accepted design).

Verify

bash

find output -name "*.cif" | wc -l  # Should match num_samples

Troubleshooting

Verify config first: Always run boltzgen check config.yaml before running the full pipeline Slow generation: Use fewer designs for initial testing, then scale up OOM errors: Use A100-80GB or reduce --num-designs Wrong binding site: Residue indices use label_seq_id (1-indexed), check in Molstar viewer

Error interpretation

Error	Cause	Fix
`RuntimeError: CUDA out of memory`	Large design or long protein	Use A100-80GB or reduce designs
`FileNotFoundError: *.cif`	Target file not found	File paths are relative to YAML location
`ValueError: invalid chain`	Chain not in target	Verify chain IDs with Molstar or PyMOL
`modal: command not found`	Modal CLI not installed	Run `pip install modal && modal setup`

Next: Validate with boltz or chai → protein-qc for filtering.

← v1.0.0 All versions