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.

Wisp execution

Use python only for bounded interactive checks. For a long or GPU-backed

workload, require a selected and probed ssh:<alias> context and load

remote-compute-ssh. Put the documented invocation in a self-contained project

script, activate the remote environment explicitly, stage only small files with

input_paths, and make the command write to a known absolute remote result

path. Submit it with run_in_context and register that exact ssh:// path in

output_specs. Call monitor_run once when waiting is needed, get_run once

for a snapshot, or cancel_run to stop. Do not send a scheduler submission

through the SSH-direct runner.

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.