/boltzgen

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](../../docs/getting-started.md) to set up Modal and biomodals.

Option 1: Modal (recommended)

# 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

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

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

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)

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:

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

#