Deploy Chai-1 v0.6.1: Open Cofolding Model Guide

Two paths exist for using Chai-1, and most tutorials skip the comparison entirely. You can run it locally via the chai_lab Python package, or paste your sequence into the free web server at lab.chaidiscovery.com and walk away. The web server wins on convenience – unless you need three things: batch throughput, custom restraints in code, or a protein complex big enough that the hosted version chokes on it. That’s when local deployment of this open cofolding model starts paying off.

This guide covers the local install for Chai-1 v0.6.1, released March 18, 2025. I’ll skip the architecture lecture and get into the parts that actually trip people up – the firewall error on shared clusters, the silent CUDA mismatch on older cards, and the trap of copy-pasting outdated install commands from the Hugging Face mirror.

System Requirements (and the One Spec Nobody Mentions)

According to the official chai-lab README, the package requires Linux, Python 3.10 or later, and a GPU with CUDA and bfloat16 support. That last phrase hides a real constraint: bfloat16 needs Ampere-generation silicon or newer (compute capability 8.0+). A GTX 1080 or Tesla V100 won’t work, no matter how much VRAM they have. The README never spells this out – you find out when the model loads and then crashes on the first matmul.

Hardware tiers sourced from the README (as of March 2025): A100 80GB, H100 80GB, or L40S 48GB are the recommended targets; A10 and A30 handle smaller complexes; users have reported the consumer-grade RTX 4090 working for single chains. CPU-only inference isn’t supported.

The Recommended Install Path

There’s a pip release and a Docker image. For a one-machine setup, pip wins on simplicity. Spin up a fresh environment first – Chai-1 pins specific versions of RDKit and Biopython (rdkit==2023.9.5 and biopython==1.83 per the Dockerfile) and clashes are common.

# Fresh conda env
conda create -n chai python=3.10 -y
conda activate chai

# Stable PyPI release
pip install chai_lab==0.6.1

# Verify the CLI exists
chai-lab fold --help

For bleeding-edge features not yet tagged, you can also install directly from the git main branch:

pip install git+https://github.com/chaidiscovery/chai-lab.git

One warning before you copy-paste from elsewhere. Turns out the Hugging Face model card (as of March 2025) still shows pip install chai_lab==0.4.2 – that page hasn’t caught up. Always pull the install command from the GitHub README or PyPI, not the HF mirror.

First Fold: Minimum Viable Config

Chai-1 doesn’t need a config file. It needs a FASTA, an output folder, and a GPU. Make a file called example.fasta:

>protein|name=chain_A
MAAHKGAEHHHKAAEHHEQAAKHHHAAAEHHEKGEHEQAAHHADTAYAHHKHAEEHAAQAAKHDAEHHAPKPH
>ligand|name=lig_A
CC(=O)OC1=CC=CC=C1C(=O)O

Then fold it:

chai-lab fold example.fasta ./out

First run will sit silent for a while – it’s pulling several GB of weights from chaiassets.com into your local cache. The default behavior generates five sample predictions using embeddings without MSAs or templates (per the README). If you want better accuracy and you’re okay sending your sequence to a public server, add the --use-msa-server flag, which triggers automatic MSA generation via the ColabFold MMseqs2 server.

Pro tip: Set CHAI_DOWNLOADS_DIR to a path on a large mounted volume before the first run. Weights are several GB. If you forget, they land in your home directory and you’ll be moving them later – or worse, re-downloading on every container restart.

Verifying the Install Actually Works

Two checks. First, confirm the package is importable and on the right version:

python -c "import chai_lab; print(chai_lab.__version__)"
# Expected: 0.6.1

Second, look inside ./out. You should see five .cif files (one per sample) and a scores.model_idx_*.npz per sample containing pTM, ipTM, and per-chain confidence matrices. Open one CIF in Mol* viewer to confirm the geometry looks sane.

Which raises a question worth sitting with: what does a “good” pTM score actually mean for your specific target? The model’s confidence calibration was validated on the training distribution – once you’re working on something structurally unlike those examples, high pTM doesn’t guarantee a correct prediction. Comparing against a known PDB structure first is the only real sanity check.

Common Errors and Real Fixes

Three failures come up over and over in the issue tracker.

ConnectionError to chaiassets.com. The fix comes first: download the weights on a node with internet access, rsync the cache directory to your air-gapped node, then set CHAI_DOWNLOADS_DIR to that path. The model checks the local cache before reaching out. This is the exact scenario reported in GitHub issue #318 – HTTPS to chaiassets.com is blocked on locked-down HPC clusters and the download fails silently until you see the connection error in the logs.

CUDA out of memory on consumer cards. The no-multi-GPU point matters here: Chai-1 has no native multi-GPU sharding, so four smaller cards don’t pool their memory – you’re stuck with whatever a single card has. As documented in GitHub issue #17, 10GB cards hit OOM at the default settings. Workarounds: reduce trunk recycles and diffusion timesteps via the Python API, or use a bigger single card.

Silent bfloat16 incompatibility. If you’re on a pre-Ampere card, the package imports fine and even loads weights, then dies mid-forward-pass with a cryptic dtype error. No workaround – the model assumes bfloat16 throughout. Use the web server instead.

Upgrading and Removing It

pip install --upgrade chai_lab==0.6.1
# or rebuild from main:
pip install --force-reinstall git+https://github.com/chaidiscovery/chai-lab.git

Cached weights stay compatible across recent point releases, so an upgrade won’t re-trigger the multi-GB download. Full removal:

pip uninstall chai_lab
rm -rf $CHAI_DOWNLOADS_DIR # or ~/.cache/chai if you never set the envvar
conda env remove -n chai

When Chai-1 Is the Wrong Tool

Ranking a million designed monomers without MSAs? ESMFold is faster and cheaper. One antibody-antigen interface needing publication-grade accuracy? Specialized antibody pipelines may still outperform it. Chai-1’s real advantage is heterogeneous complexes – protein plus small molecule plus nucleic acid plus glycan – especially when you can supply experimental restraints. The bioRxiv technical report shows restraints with experimental data boost performance by double-digit percentage points. The license is also a genuine differentiator: Apache 2.0 for both code and weights, usable commercially including for drug discovery.

Your next concrete step: run chai-lab fold example.fasta ./out on a known PDB target you already trust, open the predicted CIF in Mol*, and compare RMSD to the experimental structure. That’s the only way to calibrate how much to trust this model on your targets – because, as recent cofolding benchmarks have shown, performance drops sharply on systems unlike the training set.

FAQ

Can I run Chai-1 on a CPU?

No. The package requires a CUDA GPU with bfloat16 support. There’s no CPU fallback path.

How is v0.6.1 different from the v0.4.2 still shown on Hugging Face?

The HF model card is stale documentation – the pip and GitHub releases moved on without updating it. The weights downloaded by both versions are the same Chai-1 model; only the inference code is newer in 0.6.1. If you’re starting fresh, install 0.6.1 from PyPI and ignore the HF page for installation instructions.

Do I need to cite anything if I use Chai-1 in a paper?

Yes – cite the Chai-1 bioRxiv technical report (doi:10.1101/2024.10.10.615955). If you used --use-msa-server, also cite the ColabFold paper (Mirdita et al., Nature Methods 2022), since the MSA pipeline pings their server.