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

# JackHMMER hijacker (separate from the model runners)
curl -L "${BASE_URL}/v1/download_jackhmmer_hijacker" -o greenfold_jackhmmer_hijacker.zip

      

    


    

      

        
Reuse GreenFold alignments in JackHMMER searches

        

          Already running JackHMMER or AlphaFold with your own databases? This small executable checks
          for an existing GreenFold STO before each eligible search and runs your native JackHMMER when
          no suitable result is available. It does not change AlphaFold source code.
        

      

      

        
      

      

        The ZIP contains the executable and its setup guide. Unpack it on the machine that runs your job.
      


      

        

          Before you start
          
    
            
  • A working native jackhmmer (standard or with AF3 --seq_limit support) and the database files used by your existing command.
    • 
            
  • Python 3.10 or newer, unzip, and a POSIX shell on the job machine.
    • 
            
  • Network access from that machine to https://greenfold.dsdd.one.
    • 
          

        

        

          What this version can reuse
          
    
            
  • One protein query with an exact or approximate GreenFold match and a recognized database role: UniRef90, MGnify, UniProt, or small BFD.
    • 
            
  • Calls writing STO with -A and sending the normal report to /dev/null with -o.
    • 
            
  • Approximate matches show the inferred modification and transform a precomputed STO. Warnings or ambiguous candidates require your confirmation; unattended jobs use native JackHMMER.
    • 
            
  • Calls requiring --tblout or a database shard run natively. Reused STOs reflect GreenFold's source database and search settings.
    • 
          

        

      


      

        

          

            Unpack and enable for this shell
            
Record the native binary before adding the downloaded directory to PATH.

          

        

        
unzip greenfold_jackhmmer_hijacker.zip -d "$HOME"
chmod +x "$HOME/jackhmmer_hijacker/jackhmmer"
export REAL_JACKHMMER="$(command -v jackhmmer)"
export PATH="$HOME/jackhmmer_hijacker:$PATH"
command -v jackhmmer

        

          REAL_JACKHMMER must be the absolute path to the real binary. If your current
          jackhmmer is already another wrapper, set this variable to the underlying
          native binary instead. The final command -v should show the downloaded hijacker.
        

        

          Now run your existing JackHMMER or AlphaFold command in this shell. If your AlphaFold command
          explicitly sets --jackhmmer_binary_path, point that flag to
          $HOME/jackhmmer_hijacker/jackhmmer or remove it so AlphaFold uses PATH.
          A GreenFold hit prints GreenFold STO to stderr; a fallback prints
          Native search and its reason to stdout. Confirmation warnings go to stderr
          so AlphaFold can log them. The default public API needs no extra key.
        

      

    


    
    

      
        
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.
          

        

      


      

        
        
        
        
        
      


      

        Open Runner Documentation
        Open CLI Guide