GreenFold Runner Scripts
Back to workspace

Run models from GreenFold bundles.

  • Start with UniProt IDs, inline mutation specs, or an existing model-native input file.
  • Download paired/unpaired A3M files and model-specific JSON, YAML, FASTA, or adapter files.
  • Rewrite paths locally so AF3, Boltz, Protenix, OpenFold3, or AF2 can run without regenerating MSAs.
  • Use your existing model checkout, environment, weights, and databases.

Runner Packages

Download a small wrapper into the target model repo root, then run it from that model's own environment. The wrapper fetches the GreenFold bundle and prepares runnable local inputs.

What the package does
  • Accepts either UniProt IDs or a model-native JSON, YAML, or FASTA input file.
  • Downloads or prepares the matching GreenFold bundle.
  • Stages MSA files and generated input files in a local work directory.
  • Prints the native model command before prediction.
  • Caches downloaded bundle ZIPs under ~/.cache/greenfold/runners.
  • Includes a model-native P63313,P62328 smoke-test input and a --prepare-only command.
What you still provide
  • The model checkout and its Python/conda environment.
  • Model weights, databases, CUDA/JAX/PyTorch, and other runtime dependencies.
  • requests installed in the same environment as the runner.
Download a runner package into the target model repo root.
Command builder 

        

        

          Upload and Inspect Native Input
        

      

      

        API download examples
        
BASE_URL="https://<your-server>"

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

        

          These are thin wrappers around the official model commands. They prepare inputs, print the native command,
          and then 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[G100A]
--uniprot_ids P63313 --uniprot_ids P62328

          
Repeated flags and comma-separated IDs are both accepted.

        

        

          Existing model-native input
          
--input_file ./my_complex.json
--input_file ./my_complex.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.

        

      


      

        

          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