boltz

name	boltz
description	Structure prediction for protein, nucleic-acid, and small-molecule complexes with Boltz-2 (Passaro & Wohlwend et al. 2025, github.com/jwohlwend/boltz). Reach for this skill to validate designed binders against a target, to co-fold a protein with a SMILES or CCD ligand, or to get an open-source AlphaFold3 alternative with optional binding-affinity prediction.
license	Apache-2.0
category	biomodels
requirements	["gpu"]
metadata	{"third_party":[{"kind":"weights","name":"Boltz-2","license":"MIT","terms_url":"https://github.com/jwohlwend/boltz/blob/main/LICENSE"},{"kind":"service","name":"ColabFold MSA server (api.colabfold.com)","provider":"Steinegger Lab","info_url":"https://github.com/sokrypton/ColabFold/wiki"}]}

Boltz-2

Boltz-2 is the open-weights diffusion co-folder closest in surface to AlphaFold3: a YAML describing protein, DNA, RNA, and ligand chains in, mmCIF plus pTM/ipTM/pLDDT confidences out, with an optional small-molecule affinity head. Among our four co-fold skills it is the default for binder-validation campaigns — fully open MIT weights and the fastest sampler; pick chai1 when you want a second independent model for consensus, openfold3 when AF3-faithful settings matter, and esmfold2 when you can live without an MSA. Code and weights are MIT (PyPI boltz, github.com/jwohlwend/boltz).

Running it

# complex.yaml
version: 1
sequences:
  - protein:
      id: A
      sequence: MVTPEGNVSLVDESLLVGVTDEDRAVRS...   # target
  - protein:
      id: B
      sequence: AIQRTPKIQVYSRHPAENG...            # binder
  - ligand:
      id: L
      smiles: 'N[C@@H](Cc1ccc(O)cc1)C(=O)O'      # or  ccd: SAH

boltz predict complex.yaml \
    --use_msa_server --out_dir out/ --recycling_steps 3 --diffusion_samples 5

Each protein chain needs an MSA; without one the run exits before the model loads. --use_msa_server queries api.colabfold.com (expect a 30–90 s pause per chain) and is the right default unless you already have an .a3m to name under msa: in the YAML. Setting msa: empty forces single-sequence mode — that is an accuracy sacrifice, not a speed or memory optimization, because the MSA search runs on CPU before the GPU stage starts.

Per input the output lands at out/boltz_results_complex/predictions/complex/. Read confidence_complex_model_0.json first: iptm > 0.5 is the community pass line for an interface, complex_plddt > 0.7 for the fold itself, and confidence_score is the weighted aggregate the structures are ranked by. Structures themselves are complex_model_{0..N-1}.cif (or .pdb with --output_format pdb).

Affinity head

Add a properties: block naming one ligand chain as the binder and Boltz-2 predicts protein–small-molecule binding affinity alongside the structure:

properties:
  - affinity:
      binder: L            # the ligand chain id, not the protein

Output gains affinity_complex.json next to the confidence file: affinity_pred_value is log10(IC50 in μM) — lower is tighter (≈0 → 1 μM, −3 → 1 nM); affinity_probability_binary is the 0–1 binder-vs-non-binder score and is what to rank hits by. One affinity ligand per input; the binder must be a ligand chain (no protein–protein affinity), and Boltz v2.2.x caps affinity ligands at 128 atoms. FASTA inputs cannot request affinity at all.

msa: empty is an accuracy hit, not a memory save

Single-sequence mode has been suggested elsewhere as a way to fit smaller GPUs. It does not help: the MSA search is CPU-side, so --use_msa_server versus msa: empty changes nothing about peak VRAM. If you OOM, lower --diffusion_samples or --max_parallel_samples, or move to an 80 GB tier; do not trade away the MSA for it.

Missing fast kernels are slow, not fatal

ImportError for cuequivariance_ops_torch or its libcue_ops.so means the compiled triangle-kernel package is not on the loader path. --no_kernels falls back to the reference PyTorch path — roughly 2× slower, numerically identical, so it is the right unblock for a one-off and the wrong choice for a campaign.

Errors worth recognizing

You see	It means / do this
Missing MSA's in input and --use_msa_server flag not set	A protein chain has no MSA — add --use_msa_server or set msa: to an .a3m path in the YAML.
ImportError: ... cuequivariance_ops_torch / libcue_ops.so	Fast-kernel wheel not visible — add --no_kernels (slower, correct) or fix the env's LD_LIBRARY_PATH.
KeyError: 'iptm' reading the confidence JSON	Single-chain input — ipTM is interface-only; read ptm instead.
No affinity_*.json in output	Used FASTA input, or the YAML is missing the properties: block — see Affinity head above.

---

Next: compute clash and interface metrics on passing complexes, or feed them back to proteinmpnn for another design round.