| name | protenix |
| description | Run Protenix — ByteDance's open-source, trainable reproduction of AlphaFold 3 for high-accuracy biomolecular structure prediction. Protenix folds complexes of proteins, DNA, RNA, small-molecule ligands, and ions in one pass, with post-translational/nucleotide modifications, covalent bonds, MSAs, templates, and optional pocket/contact constraints. Use this skill when: (1) Predicting the 3D structure of a **protein / nucleic-acid / ligand
complex** from sequences + ligand specs (the headline use case),
(2) Folding a **single protein** (monomer or homo-/hetero-oligomer via
`count` / `id`) with an MMseqs2 MSA searched automatically,
(3) Modeling **protein–ligand** binding where the ligand is a CCD code, a
SMILES string, or a 3D structure file (SDF/MOL/MOL2/PDB),
(4) Predicting **protein–DNA / protein–RNA** complexes, optionally with RNA
MSA, modified bases, and double-stranded DNA (two complementary strands),
(5) Adding **covalent bonds** (e.g. glycosylation, covalent inhibitors,
cyclic peptides) or **PTMs / modified residues** by CCD code,
(6) Steering predictions with **soft pocket / contact constraints** (the
`constraint` model) to bias an interface toward known epitopes/pockets,
(7) Trading accuracy for speed via the **mini / tiny** model variants for
high-throughput screening, or maximizing accuracy with `protenix-v2`,
(8) Generating inputs: converting a **PDB/CIF → input JSON** (`protenix json`)
or running **MSA / template / RNA-MSA search** as a standalone preprocess
step (`protenix msa` / `mt` / `prep`),
(9) Ranking and reading **confidence** (ranking_score / pLDDT / pTM / ipTM,
per-chain and per-chain-pair) to pick the best of N samples × M seeds.
This skill is written for running Protenix from an **Apptainer / Singularity SIF container** (the runtime is heavy: torch 2.7 + CUDA 12.6 + DeepSpeed + cuEquivariance + JIT-compiled layer-norm / Evoformer-attention CUDA kernels). The Protenix repo at `~/Repos/Protenix` ships a ready-made `apptainer/` directory (`protenix.def`, `build.sh`, `download_weights.sh`, `run_protenix.sh`). The skill covers building the SIF, the host-side bind-mounted weights layout (`$PROTENIX_ROOT_DIR/checkpoint` + `/common`), the `apptainer run --nv` invocation pattern, every `protenix` subcommand and `pred` flag, the AlphaFold-Server-style input JSON (entities, modifications, covalent bonds, MSA/template paths, pocket/contact constraints), the model zoo and which to pick, the output layout (`<name>/<seed>/<name>_<seed>_sample_*.cif` + summary confidence JSON), and how to rank by confidence.
Limitations: Apache-2.0; needs a CUDA GPU (data-cutoff 2021-09-30 for most checkpoints); `protenix-v2.pt` is not currently served publicly; ESM/ISM checkpoints need the ~5 GB ESM2-3B weights and are not downloaded by default; pocket/contact constraints require the `constraint` checkpoint; templates & RNA-MSA are supported only by the v1.0.0 / 20250630 / v2 models.
Pairs with: `boltz` / `chai-lab` (alternative AF3-class co-folding models — cross-check predictions or pick the tool that handles your modality best), `boltzgen` / `disco` / `foundry` (design binders/enzymes, then validate the complex with Protenix), `placer` (atomistic ligand-pose / side-chain refinement and pose scoring on a Protenix pocket), `protflow` (wrap Protenix as a pipeline step at cluster scale), `fair-esm` (ESMFold / embeddings).
|
| license | Apache-2.0 |
| category | protein-design |
| tags | ["protein-design","structure-prediction","alphafold3","complex-prediction","protein-ligand","protein-nucleic-acid","msa","diffusion","constraints","apptainer","singularity","bytedance"] |
| repo | https://github.com/bytedance/Protenix |
| biorxiv | https://www.biorxiv.org/content/10.1101/2025.01.08.631967 |
Protenix — open-source AlphaFold 3 (Protein + X)
What this is
Protenix is ByteDance's open-source, trainable reproduction of AlphaFold 3:
a Pairformer + diffusion model that predicts the all-atom 3D structure of a
biomolecular complex from its components. One job can mix proteins, DNA, RNA,
small-molecule ligands, and ions, with post-translational/nucleotide
modifications, inter-entity covalent bonds, MSAs, structural templates, and
optional soft pocket/contact constraints. It outputs CIF structures plus
AlphaFold3-style confidence scores. Released under Apache-2.0 (code +
weights), free for commercial use.
The repo at ~/Repos/Protenix is v2.0.0 and exposes a protenix CLI
(installed as a console script). It ships a ready-made Apptainer setup under
apptainer/, which is the path this skill is built around.
Read first — three things that trip people up:
- Weights live on the host, not in the image. They are bind-mounted at
launch and resolved from
$PROTENIX_ROOT_DIR (checkpoint/ + common/).
Download them once with apptainer/download_weights.sh.
- Use
--use_default_params true. It sets the right cycle/step for the
chosen model (base = 10/200, mini/tiny = 4/5). Without it you get generic
defaults that may not match the checkpoint.
- The first run JIT-compiles CUDA kernels (layer-norm, Evoformer
attention) into
$TORCH_EXTENSIONS_DIR — slow once, cached after.
When to use Protenix vs. alternatives
| You want… | Use |
|---|
| Full complex structure (protein + DNA/RNA + ligand + ions) from sequence | Protenix |
| Cross-check an AF3-class prediction with a second model | Protenix + boltz / chai-lab |
| Best antibody–antigen / ligand accuracy (if you have the weights) | Protenix protenix-v2 |
| High-throughput screening (many targets, lower cost) | Protenix mini / tiny |
| Design a binder / enzyme, then validate the complex | boltzgen/disco/foundry → Protenix |
| Refine/score a ligand pose & side chains in one pocket | placer (atomistic; runs on a Protenix output) |
| Binding affinity prediction | boltz (Boltz-2) — Protenix predicts structure + confidence, not ΔG |
A common loop: fold the complex with Protenix → inspect ranking_score /
ipTM → hand the top sample's pocket to placer for atomistic ligand/side-chain
refinement, or cross-check the fold with chai-lab / boltz.
Quickstart — run from the Apptainer SIF
The heavy runtime (torch 2.7, CUDA 12.6, DeepSpeed, cuEquivariance, JIT CUDA
kernels) is packaged once into a SIF. The Protenix repo already contains the
definition and helper scripts under apptainer/.
1) Build the SIF (one-time, from the repo root)
cd ~/Repos/Protenix
bash apptainer/build.sh
build.sh stages a clean copy of the repo (minus .git/caches/outputs) and
bakes it into the image; the source lives at /opt/protenix inside. See
references/installation.md for fakeroot vs. cluster builds, cache dirs, and the
CUTLASS/kernel details.
2) Download model weights to the host (one-time)
PROTENIX_ROOT_DIR=/shared/ModelWeights/Protenix bash apptainer/download_weights.sh
This fetches the non-ESM checkpoints (~7.5 GB) into $PROTENIX_ROOT_DIR/checkpoint
and the CCD / cluster / release-date caches into $PROTENIX_ROOT_DIR/common.
Weights are not baked into the SIF — they are bind-mounted at run time. See
references/models.md for the model list and references/installation.md for
the directory layout.
3) Predict (GPU)
The wrapper handles --nv and the weights bind-mount:
cd ~/Repos/Protenix
apptainer/run_protenix.sh pred \
-i examples/input.json \
-o ./output \
-n protenix_base_default_v1.0.0 \
--use_default_params true \
--seeds 101 --sample 5
Equivalent manual invocation:
apptainer run --nv \
--bind /shared/ModelWeights/Protenix:/shared/ModelWeights/Protenix \
--env PROTENIX_ROOT_DIR=/shared/ModelWeights/Protenix \
apptainer/protenix.sif pred -i examples/input.json -o ./output \
-n protenix_base_default_v1.0.0 --use_default_params true
--nv exposes the host GPU (required; CPU is impractical).- Apptainer auto-mounts
$HOME and $PWD, so inputs/outputs under them resolve
without extra binds. Bind anything outside with --bind SRC:DST.
- Restrict GPUs with
--env CUDA_VISIBLE_DEVICES=0.
- Don't launch from inside a Protenix checkout unless you mean to — cwd
shadows the baked-in
/opt/protenix and JIT artifacts get written into your
tree (harmless, but messy). Run from a data dir. See references/installation.md.
4) Read the output
output/<name>/<seed>/
├── <name>_<seed>_sample_0.cif # predicted structure
├── <name>_<seed>_summary_confidence_sample_0.json # scores
└── ... # one per sample
Rank samples by ranking_score (higher = better; Protenix sorts by it by
default). Full layout + every score in references/outputs.md.
The protenix CLI at a glance
| Subcommand | Purpose |
|---|
protenix pred | Run structure prediction on a JSON file/dir (the main command) |
protenix json | Convert PDB/CIF → Protenix input JSON (--altloc, --assembly_id) |
protenix msa | MSA search (MMseqs2) for a JSON or FASTA; writes MSA paths back |
protenix mt | MSA search then template search |
protenix prep | MSA + template + RNA-MSA search (full input preprocess) |
Most-used pred flags (short / long → meaning):
| Flag | Meaning |
|---|
-i/--input | Input JSON file or directory of JSONs (required) |
-o/--out_dir | Output dir (default ./output) |
-n/--model_name | Checkpoint, e.g. protenix_base_default_v1.0.0 (default) |
--use_default_params | Set true — picks correct cycle/step per model |
-s/--seeds | Comma-separated seeds, e.g. 101,102,103 |
-e/--sample | Diffusion samples per seed (default 5) |
-c/--cycle / -p/--step | Pairformer cycles / diffusion steps (override) |
--use_msa | Use MSA (default true; auto-searches if no paths in JSON) |
--use_template / --use_rna_msa | Enable templates / RNA MSA (v1.0.0/20250630/v2 only) |
--need_atom_confidence | Also emit per-atom confidence |
-d/--dtype | bf16 (default) or fp32 |
Every flag (including the kernel selectors --trimul_kernel / --triatt_kernel,
--msa_server_mode, --use_tfg_guidance, and the hmmer/RNA-DB paths) is
documented in references/cli.md.
Input JSON in 30 seconds
Input is an AlphaFold-Server-style list of jobs. Each job has a name and a
list of sequences (entities). Minimal protein monomer:
[
{
"name": "my_protein",
"sequences": [
{ "proteinChain": { "sequence": "MAQGSHQ...HF", "count": 1 } }
]
}
]
Entities: proteinChain, dnaSequence, rnaSequence, ligand, ion.
Ligands accept a CCD code ("CCD_ATP"), a SMILES string, or a 3D file
("FILE_/path/lig.sdf"). You can add modifications (PTMs), covalent_bonds
between entities, precomputed MSA/template paths, and soft contact/pocket
constraints. Full schema with copy-paste examples: references/inputs.md and
examples/input_examples.md.
Choosing a model
protenix_base_default_v1.0.0 — recommended default (368 M, AF3-aligned
data cutoff, supports MSA + templates + RNA MSA).protenix_base_20250630_v1.0.0 — same size, newer data cutoff (2025-06-30)
for practical/applied use.protenix-v2 — best accuracy (464 M, antibody-antigen gains) but the
checkpoint is not currently served publicly (download returns 403).protenix_base_constraint_v0.5.0 — required for pocket/contact
constraints.protenix_mini_default_v0.5.0 / protenix_tiny_default_v0.5.0 — fast,
for high-throughput screening (cycle 4 / step 5).protenix_mini_esm_v0.5.0 / _ism_ — single-sequence (no MSA) ESM-based;
need the ESM2-3B weights and are not downloaded by the default script.
Full table (params, features, default cycle/step) in references/models.md.
Confidence — what to rank on
Each sample's *_summary_confidence_*.json reports AlphaFold3-style scores:
ranking_score — the headline ranking metric (higher = better). Protenix
sorts samples by it.plddt — per-residue confidence, higher better.ptm / iptm — global / interface predicted TM-score (→1 better); use
iptm and chain_pair_iptm to judge interfaces.has_clash, gpde, disorder, per-chain breakdowns.
Definitions and how to combine them in references/outputs.md.
Reference index
references/installation.md — building the SIF (apptainer/ scripts,
fakeroot, cluster builds), the host weights layout + download_weights.sh,
bind-mounts, GPU selection, kernel JIT cache, conda/Docker alternatives.references/cli.md — every protenix subcommand and pred flag with semantics.references/inputs.md — input JSON schema: entities, modifications, ligands,
covalent bonds, MSA/template paths, pocket/contact constraints, protenix json.references/models.md — the model zoo, capabilities, default params, weights.references/outputs.md — output layout + every confidence score and how to rank.references/troubleshooting.md — build, weights, GPU/kernel, and input failures.examples/run_examples.sh — copy-paste run_protenix.sh / apptainer invocations.examples/input_examples.md — input JSONs (monomer, complex+ligand, DNA,
covalent bond, constraints).
Installing this skill
mkdir -p ~/.claude/skills
ln -s "$(pwd)" ~/.claude/skills/protenix
cp -R . ~/.claude/skills/protenix
After that, an agent invokes it via Skill(skill="protenix").
Citation
Protenix, ByteDance AML AI4Science Team. Apache-2.0.
ByteDance AML AI4Science Team et al.
Protenix — Advancing Structure Prediction Through a Comprehensive
AlphaFold3 Reproduction. bioRxiv 2025.01.08.631967.
https://www.biorxiv.org/content/10.1101/2025.01.08.631967
Zhang et al. Protenix-v2: Broadening the Reach of Structure Prediction
and Biomolecular Design. bioRxiv 2026.04.10.717613.
