Automate preparation and model runs.

Use the same GreenFold target resolution and model-specific inputs as the web Prepare workflow, but run them repeatedly from your local model checkout. The runner can stop after preparation or continue into the model's native prediction command.

Interactive Prepare in the browser Build and inspect one target, then download its prepared ZIP.

Reusable local workflow Local runner & automation Repeat preparation, use existing input files, or process supported batches inside the model environment.

Build a reusable local workflow

Select the model first. The runner uses the same target meanings and prepared files as the browser workflow, then stages them in your local checkout and prints or executes the native model command.

Step 1 Download once

Put the small runner package in the selected model's repository and activate that model's environment.

Step 2 Use the same target inputs

Provide UniProt chain specs, one model-native file, or a supported batch of model-native files.

Step 3 Prepare or predict

Keep --prepare-only while inspecting outputs; remove it when the local model setup is ready.

Download once, then reuse the runner for later targets.

Recommended first command

Understand the runner parameters

Start with the recommended command above. The cards below explain its parameters and the alternative input parameters you may substitute when starting from a native file or supported batch.

Build or inspect one input in Prepare

What the runner installs and what you still provide

Runner responsibilities

Fetch and cache the matching GreenFold prepared bundle.
Stage MSA and model-native input files locally.
Complete supported missing-chain fallback MSAs when needed.
Print the native model command before prediction.

Your local environment

The model checkout and its Python/conda environment.
Model weights, databases and runtime dependencies.
requests installed in the model environment.

Download runners through the API

BASE_URL="https://greenfold.dsdd.one"

curl -L "${BASE_URL}/v1/download_runner/af3" -o greenfold_af3_runner.zip
curl -L "${BASE_URL}/v1/download_runner/boltz" -o greenfold_boltz_runner.zip
curl -L "${BASE_URL}/v1/download_runner/protenix" -o greenfold_protenix_runner.zip
curl -L "${BASE_URL}/v1/download_runner/openfold" -o greenfold_openfold_runner.zip
curl -L "${BASE_URL}/v1/download_runner/af2" -o greenfold_af2_runner.zip

# AF2 adapter files only
curl -L "${BASE_URL}/v1/download_af2_adapter" -o af2_adapter.zip

How the runners work

Thin wrappers around the official model commands: they prepare inputs, run the local partial-MSA helper when needed, print the native command, and run the model only when you omit --prepare-only.

Basic workflow

1. Download the runner ZIP for your model.
2. Unzip it in the model repository root.
3. Activate that model's Python/conda environment.
4. Run the matching run_greenfold_*.py script.
5. Use --prepare-only first if you want to inspect files before prediction.
6. Use --refresh-cache to redownload a bundle, or --no-cache to bypass cache.

UniProt input format

--uniprot_ids P63313
--uniprot_ids P63313,P62328
--uniprot_ids P63313[I10A]
--uniprot_ids P63313 --uniprot_ids P62328

Repeated flags and comma-separated IDs are both accepted.

Existing model-native input

--input_file ./greenfold_test_P63313_P62328.json
--input_file ./greenfold_test_P63313_P62328.yaml
--input_file ./target.fasta

The runner uploads the file to GreenFold, reverse-maps protein sequences, downloads staged MSAs, preserves non-protein entities, and then calls the model's native command. For Boltz, OpenFold3, and Protenix, mixed inputs default to GreenFold-ColabFold partial fallback: the server packages existing GreenFold MSAs, then the runner runs the bundled helper locally to generate missing-chain ColabFold/MMseqs2 MSAs before prediction.

Single-sequence protein chains

--input_file ./design_complex.json
--skip_msa_for_chain B
--skip_msa_for_chain complex_1:B

Repeat the flag for de novo protein chains that should skip reverse UniProt lookup and all MSA processing. OpenFold3 inputs with multiple queries use QUERY_NAME:CHAIN_ID. This option requires a model-native input and is not combined with --uniprot_ids.

AF3

Before prediction, add the AF3-native paths required by your installation, especially --model_dir and --db_dir. The example intentionally leaves those local paths out.

Run from an AlphaFold 3 checkout.
Requires configured model weights and databases.

python run_greenfold_af3.py \
  --uniprot_ids P63313,P62328 \
  --output_dir ./outputs \
  --prepare-only

Boltz

Use the Boltz flags and paths from your own Boltz installation. Add any local checkpoint, device, recycling, or output options that your normal boltz predict command requires.

Run where boltz predict already works.
Uses GreenFold CSV MSA inputs instead of Boltz's MSA server.

python run_greenfold_boltz.py \
  --uniprot_ids P63313,P62328 \
  --output_dir ./boltz_out \
  --prepare-only

Protenix

Set PROTENIX_ROOT_DIR and any Protenix-native model or database options according to your local Protenix checkout before running prediction.

Set PROTENIX_ROOT_DIR so Protenix can find CCD resources.
Use --model-name if your installation uses another released model.

export PROTENIX_ROOT_DIR="/path/to/Protenix/"
python run_greenfold_protenix.py \
  --uniprot_ids P63313,P62328 \
  --output_dir ./protenix_out \
  --prepare-only

OpenFold3

Run this only inside a working OpenFold3-preview setup. Keep using the model, checkpoint, database, and runtime options required by your local OpenFold3 installation.

Targets OpenFold3-preview style inputs.
Sets --use_msa_server=False because MSA files are already staged.

python run_greenfold_openfold.py \
  --uniprot_ids P63313,P62328 \
  --output_dir ./openfold_out \
  --prepare-only

AF2

Before prediction, add --data_dir for your AF2 database installation and keep any other AF2-native flags your setup needs. The default command is safe to copy for --prepare-only.

AF2 runner ZIP includes the adapter files.
Default --output_dir is the downloaded bundle directory.
Only override it if you need a custom parent for <input_name>/msas/.

python run_greenfold_af2.py \
  --uniprot_ids P63313,P62328 \
  --use_precomputed_msas=True \
  --model_preset=multimer \
  --max_template_date=2020-05-14 \
  --db_preset=reduced_dbs \
  --models_to_relax=best \
  --prepare-only

AF2 also needs run_from_a3m.py, pipeline_pre_run.py, and greenfold_af2_no_docker.py in the AF2 repo root. Only set --output_dir manually if you understand that it must contain <input_name>/msas/.

Open Runner Documentation Open CLI Guide