Boltz Agent Skill

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.