/boltzgen

id: "skill_5166b5795e7f473d9c80c23c3cdcc903"
name: "boltzgen"
display-name: "BoltzGen — Antibody / Nanobody / Binder Design"
short-description: "Antibody, nanobody, and de novo binder design using BoltzGen (diffusion + AntiFold inverse folding + Protenix refolding). Use when the user needs to design a binder against a protein target with a known epitope or hotspot set."
category: "tool"
keywords: "antibody, nanobody, VHH, scFv, Fab, binder design, BoltzGen, diffusion, Protenix, AntiFold, ipSAE, ipTM, epitope, hotspot, scaffold, entities YAML"
version: "1.0"
last-updated: "2026-05-20"

BoltzGen — Antibody / Nanobody / Binder Design

BoltzGen is an all-atom diffusion model that generates antibody, nanobody, and de novo miniprotein backbones conditioned on a target structure and a set of binding (hotspot) residues. Sequences are assigned by AntiFold, then each design is independently refolded with Protenix to produce ipTM, pTM, pLDDT, ipSAE, and CA-RMSD metrics. This skill teaches the exact **Write → Bash → Read** pattern for invoking BoltzGen via its CLI on local GPU (default), HPC (RunPod via `by-deploy-compute`), or Tamarind cloud.

The legacy CLI name was `proteus-ab`. It has been renamed to **BoltzGen** throughout. If you see `proteus-ab` in older docs or scripts, treat it as the same engine — the binary on PATH is now `boltzgen`.

---

When to Use This Skill

Use BoltzGen when you have:

• ✅ **A cleaned target structure** (CIF or PDB) with unambiguous chain IDs
• ✅ **A defined epitope or hotspot set** expressed in `label_seq_id` numbering
• ✅ **A modality decision in hand** — VHH single-domain, full antibody Fab, or de novo miniprotein
• ✅ **GPU compute available** — local (CUDA-capable, ≥24 GB VRAM), HPC (RunPod), or Tamarind cloud
• ✅ **A design budget** — typical preview is 10–20 designs; production is 50–200

Do NOT use BoltzGen when:

• ❌ **You need to validate a known antibody sequence against a target** → use **Protenix** directly (no design needed)
• ❌ **You need to score or filter an existing batch of designs** → use **by-scoring** (ipSAE) and **by-screening**
• ❌ **No epitope is known or characterised** → run **by-research** + **by-epitope-analysis** first; designing with no `binding_types` is wasteful
• ❌ **You want a small-molecule binder** → BoltzGen designs proteins/peptides only
• ❌ **You need ranked, published results** → use **by-display** / `/by:results`

---

Quick Start

A 20-design VHH preview against TNF-α (PDB 1TNF, epitope residues 45–52 and 78–85) on a local GPU:

# Step 1: write spec via the Write tool — see scripts/boltzgen_submit.py for a builder
# Step 2: submit (dry-run prints the command; remove --dry-run to launch)
python scripts/boltzgen_submit.py \
  --spec workspace/tnf_spec.yaml \
  --protocol nanobody-anything \
  --num-designs 20 \
  --budget 48 \
  --target local \
  --output workspace/tnf_out

# Step 3: parse results into a CSV with sequences + metrics
python scripts/parse_designs.py \
  --output-dir workspace/tnf_out \
  --csv workspace/tnf_designs.csv

Expected runtime: ~10–25 min on a single H100/A100 (Stage 4 Protenix refolding dominates). Expected output: a CSV ranked by `iptm` descending, typically 60–80% of designs with `iptm > 0.4`, 20–40% with `iptm > 0.6`.

---

Installation

| Software | Version | License | Commercial Use | Installation | |----------|---------|---------|----------------|--------------| | BoltzGen | ≥0.1.0 | MIT | ✅ Permitted | Clone https://github.com/HannesStark/boltzgen; install per repo README | | Protenix | v1.x (368M) | Apache-2.0 | ✅ Permitted | Bundled with BoltzGen install; downloads weights on first run | | AntiFold | ≥1.0 | MIT | ✅ Permitted | Bundled with BoltzGen install | | CUDA toolkit | ≥11.8 | NVIDIA EULA | ✅ Permitted | Match your driver version | | Python | ≥3.10 | PSF | ✅ Permitted | Use the conda env shipped by BoltzGen | | pyyaml | ≥6.0 | MIT | ✅ Permitted | `pip install pyyaml` (used by the helper scripts) |

**System requirements:**

| Requirement | Details | |-------------|---------| | BoltzGen path env | `BOLTZGEN_DIR` (or legacy `PROTEUS_AB_DIR`) pointing at the repo clone | | Model weights env | `PROTEUS_MODELS_DIR` — typically `~/.cache/boltzgen` | | LayerNorm env | `LAYERNORM_TYPE=openfold` — **mandatory** for correct inference | | GPU | CUDA-capable, ≥24 GB VRAM recommended (40 GB for `antibody-anything` with budget ≥ 128) | | CLI binary | `boltzgen` (on PATH after env setup) |

**License Compliance:** All packages permit commercial use in AI applications.

For HPC (RunPod) deployment, see the **by-deploy-compute** skill — it handles container image selection, secret injection, GPU type, and S3 mounting. For Tamarind cloud, point the helper scripts at `--target tamarind` (requires `TAMARIND_API_KEY` env var).

---

Inputs

**Required:**

• **Target structure file** — CIF (preferred) or PDB
• Single chain or multi-chain
• Clean chain IDs (`A`, `B`, …) — no `0` or unusual letters
• Resolved coordinates for the epitope region (no missing density)
• **Entities YAML spec** — see `references/entities-yaml-spec.md`
• Lists the target file, chains to include, and `binding_types` epitope ranges
• Optional scaffold entity (Fab framework or nanobody scaffold)
• **Protocol** — `nanobody-anything`, `antibody-anything`, `protein-anything`, `peptide-anything`, or `protein-redesign`

**Alternative inputs:**

• **Binding residue list (Python list of ints)** — converted to range notation by `boltzgen_submit.py` (see range table in `references/entities-yaml-spec.md`)
• **Pre-built scaffold YAML** — point a second entity at `$BOLTZGEN_DIR/example/fab_scaffolds/*.yaml` or `nanobody_scaffolds/*.yaml`

**Optional:**

• **MSA mode** — `none` (default), `precomputed` (A3M files), or `nim` (NVIDIA NIM API)
• **Budget** — diffusion steps; 48 preview, 96–128 production
• **`--prefilter`** — drops low-quality designs before the expensive Protenix refolding (recommended for