Foundry Protein Design Toolkit Reference

Foundry provides core protein design and prediction tools. All tools require GPU compute and are designed to run on Vast.ai instances using a pre-built Docker image that includes all tools, checkpoints, and dependencies.

Tools Overview

Docker Image

A pre-built Docker image based on vastai/base-image:cuda-12.4.1-auto is available with everything pre-installed:

• •Python 3.12, PyTorch with CUDA 12.4
• •Foundry with all model extras (rc-foundry[all])
• •All checkpoints pre-downloaded to /root/.foundry/checkpoints
• •Enhanced MPNN weights included

When launching Vast.ai instances, use this image with:

vastai create instance <OFFER_ID> --image <FOUNDRY_DOCKER_IMAGE> --disk 64 --ssh

No --onstart-cmd is needed — the image is ready to use immediately. The working directory is /workspace.

Available Checkpoints

All checkpoints are pre-installed in the Docker image at /root/.foundry/checkpoints:

Checkpoint env: FOUNDRY_CHECKPOINT_DIRS=/root/.foundry/checkpoints

Tool 1: RFdiffusion3 (RFD3)

All-atom generative model for designing protein structures under complex constraints: protein binders, enzyme active sites, nucleic acid binders, small molecule binders, symmetric assemblies.

CLI

rfd3 design out_dir=<OUTPUT_DIR> inputs=<INPUT_JSON> [OPTIONS]

Key Parameters

Sampler Parameters

Input JSON Format

The input is a JSON file mapping example names to design specifications:

{
    "design_name": {
        "input": "./path/to/target.pdb",
        "contig": "40-120,/0,A1-100",
        "length": "140-160",
        "ligand": "NAI,ACT",
        "unindex": "A108,A139",
        "select_fixed_atoms": {
            "A108": "ND2,CG",
            "A139": "OG,CB,CA"
        },
        "select_hotspots": {
            "E64": "CD2,CZ"
        },
        "is_non_loopy": true,
        "infer_ori_strategy": "hotspots",
        "dialect": 2
    }
}

Key input fields:

• •input: Path to target structure (PDB/CIF)
• •contig: Contig specification — defines which residues to keep/design and chain breaks
• •length: Length range for designed protein (e.g., "140-160")
• •ligand: Comma-separated ligand residue names to include
• •unindex: Residues to unindex (make designable in position)
• •select_fixed_atoms: Per-residue atom selections to fix
• •select_hotspots: Target hotspot residues for interface design
• •is_non_loopy: Disable loop-only design mode
• •infer_ori_strategy: How to determine orientation (hotspots)
• •dialect: Input dialect version (use 2 for latest)
• •partial_t: Partial diffusion timestep (for refinement)
• •ori_token: Orientation token indices

Output

• •{name}.cif — Designed all-atom structures
• •{name}.json — Full design metadata
• •Trajectory files (if dump_trajectories=True)

Tool 2: RosettaFold3 (RF3)

All-atom biomolecular structure prediction for proteins, nucleic acids, ligands, and complexes.

CLI

rf3 fold inputs=<INPUT_FILE_OR_DIR> [OPTIONS]

Key Parameters

Structural Control

• •template_selection — AtomSelection syntax for template regions (e.g., "[A, B/*/1-42]")
• •ground_truth_conformer_selection — Fix ligand conformations (e.g., "[C, D]")
• •cyclic_chains — List of chain IDs to cyclize

Input JSON Format

[
    {
        "name": "example_prediction",
        "components": [
            {
                "seq": "MTSENPLLALREK...",
                "chain_id": "A",
                "msa_path": "path/to/protein.a3m"
            },
            {
                "ccd_code": "MG"
            },
            {
                "smiles": "[nH]1cc[nH+]c1"
            },
            {
                "path": "path/to/ligand.sdf"
            }
        ],
        "template_selection": ["A"],
        "ground_truth_conformer_selection": ["C"]
    }
]

Component types:

• •seq + optional msa_path — Protein/nucleic acid sequence (supports non-canonical: (PTM))
• •ccd_code — CCD compound code (e.g., MG, NAG)
• •smiles — Small molecule SMILES string
• •path — Structure file (CIF, PDB, SDF)

AtomSelection syntax: CHAIN/RES_NAME/RES_ID/ATOM_NAME

• •A — all atoms in chain A
• •A/*/5-10 — residues 5-10 in chain A
• •B/*/1-42, B/*/49-63 — multiple regions (CDR framework)

Output

• •{name}_metrics.csv — Overall confidence metrics (pTM, pLDDT, ipTM)
• •{name}.score — Granular per-atom metrics
• •{name}_model_0.cif.gz ... {name}_model_N.cif.gz — Predicted structures

Tool 3: ProteinMPNN / LigandMPNN / SolubleMPNN / Enhanced MPNN

Lightweight inverse-folding models for fixed-backbone protein sequence design.

CLI

mpnn --model_type <MODEL_TYPE> --structure_path <STRUCTURE> [OPTIONS]

Or from JSON config:

mpnn --config_json config.json

Model Variants

Enhanced MPNN

Enhanced MPNN is a fine-tuned LigandMPNN trained with ResiDPO (Residue-level Designability Preference Optimization). Instead of optimizing for native sequence recovery like standard MPNN, it directly optimizes for designability — whether designed sequences fold into the target structure with high confidence (as measured by AlphaFold2 pLDDT scores).

Performance improvements over standard LigandMPNN:

• •Enzyme design: ~2.7x higher success rate (17.6% vs 6.6%)
• •Binder design: ~2.3x higher success rate (16.1% vs 7.1%)
• •Makes previously "undesignable" backbones designable — doubles the fraction of viable backbone scaffolds

How it works:

• •ResiDPO decouples preference learning from KL regularization at the residue level
• •Residue-level Preference Learning (RPL) improves positions where pLDDT is low
• •Residue-level Constraint Learning (RCL) preserves knowledge at positions already working well
• •Trained on 19k PDB structures with AF2 pLDDT as the reward signal

When to use Enhanced MPNN (recommended for most de novo design):

• •Binder or enzyme design pipelines (RFD3 → MPNN → RF3 validation)
• •Any scenario where standard MPNN yields low designability/validation rates
• •Maximizing the fraction of designs that pass structure validation

When to prefer standard MPNN/LigandMPNN:

• •When sequence recovery (similarity to native) matters more than designability
• •Benchmarking against published results using original models

Usage — same CLI as LigandMPNN, just swap the checkpoint:

mpnn --model_type ligand_mpnn \
  --checkpoint_path /root/.foundry/checkpoints/enhanced_mpnn_step_80000.pt \
  --structure_path backbone.cif \
  --temperature 0.1 \
  --number_of_batches 8

Key Parameters

Global:

• •--model_type — protein_mpnn or ligand_mpnn
• •--checkpoint_path — Path to model weights
• •--is_legacy_weights — Set True for original repository weights (not needed for Enhanced MPNN)
• •--out_directory — Output directory
• •--write_fasta — Write FASTA output (default: True)
• •--write_structures — Write designed structures (default: True)

Per-input:

• •--structure_path — Input structure (CIF/PDB)
• •--batch_size — Sequences per batch (default: 1)
• •--number_of_batches — Number of batches (default: 1)
• •--temperature — Sampling temperature, controls diversity (default: 0.1)
• •--seed — Random seed
• •--designed_chains — Chains to redesign
• •--fixed_chains — Chains to keep fixed
• •--designed_residues — Specific residues to design
• •--fixed_residues — Specific residues to fix

Advanced:

• •--omit — Amino acids to exclude (default: ["UNK"])
• •--bias — Per-residue logit bias
• •--structure_noise — Noise level (default: 0.0)
• •--symmetry_residues — Residues for symmetric design
• •--homo_oligomer_chains — Homo-oligomer chains

JSON Config Format

{
    "checkpoint_path": "enhanced_mpnn_step_80000.pt",
    "model_type": "ligand_mpnn",
    "out_directory": "./outputs/",
    "inputs": [
        {
            "structure_path": "complex.pdb",
            "name": "example",
            "seed": 42,
            "batch_size": 1,
            "number_of_batches": 5,
            "temperature": 0.1,
            "fixed_chains": ["A"],
            "designed_chains": ["B"]
        }
    ]
}

Output

• •{name}_sequences_*.fasta — Designed sequences
• •{name}_*.cif — Designed structures (if write_structures=True)

Common Design Workflows

Protein Binder Design Pipeline

1. •RFD3: Generate binder backbones targeting a protein → outputs CIF structures
2. •Enhanced MPNN: Design sequences for the generated backbones (~2.3x better success) → outputs FASTA sequences
3. •RF3: Validate designed sequences fold correctly → outputs confidence metrics

Enzyme Design Pipeline

1. •RFD3: Design enzyme scaffolds around a ligand/substrate
2. •Enhanced MPNN: Design ligand-aware sequences (~2.7x better designability) → outputs FASTA sequences
3. •RF3: Validate predicted structure matches design

Sequence Optimization

1. •Start with an existing structure (PDB/CIF)
2. •ProteinMPNN/SolubleMPNN: Redesign sequences for stability/solubility
3. •RF3: Predict structure of redesigned sequences

Vast.ai GPU Recommendations

Use the pre-built Foundry Docker image — no setup commands needed. Instance is ready to run immediately after launch.