---
title: Folding a protein | Runware Docs
url: https://runware.ai/docs/serverless/examples/protein-folding
description: Fold a sequence into a structure file, with the weights pinned to a revision so every worker loads the same ones.
relatedDocuments:
  - https://runware.ai/docs/serverless/writing-a-model
  - https://runware.ai/docs/serverless/volumes
  - https://runware.ai/docs/serverless/invoking
---
## Introduction

A protein sequence goes in and a predicted structure comes out as PDB, on the same GPUs the models API runs on.

ESMFold is MIT licensed and its weights are ungated, so you deploy it with **no token**.

## The app

**model.py**:

```python
"""Folding a protein: a sequence in, a predicted structure out.

ESMFold predicts a structure from a single sequence, with no multiple sequence
alignment and so no call out to an alignment server. The whole app is one model
and one forward pass.
"""

from __future__ import annotations

from pydantic import BaseModel, ConfigDict, Field

from runware_serverless import serve

MODEL = "facebook/esmfold_v1"

REVISION = "75a3841ee059df2bf4d56688166c8fb459ddd97a"
"""Pinned, deliberately.

A moving reference is how you end up with weights the installed version cannot
load: the checkpoint drifts, the code does not, and the worker dies at startup
with a constructor it cannot satisfy. A revision costs nothing and removes that."""

CACHE = "/weights"
"""Mount a volume here. The model is about 2.6GB, which is a download worth doing
once rather than on every cold start."""

WARMUP = "MKTAYIAKQRQISFVKSHFSRQ"
"""Folded once in ``load`` so the weights arrive before any request does."""

MAX_RESIDUES = 400
"""Attention over the sequence grows with the square of its length. The schema
publishes the ceiling, and this app enforces it: the platform checks the types it
published but not a value constraint."""

CHUNK = 64
"""Trades speed for peak memory inside the folding trunk. Lower it if a long
sequence runs out of room."""

class Request(BaseModel):
    model_config = ConfigDict(extra="forbid")

    sequence: str = Field(
        min_length=10,
        max_length=MAX_RESIDUES,
        pattern=r"^[ACDEFGHIKLMNPQRSTVWY]+$",
        description="One protein chain, as standard single-letter amino acids.",
    )

class Folded(BaseModel):
    structure: str = Field(description="The predicted structure as PDB text.")
    format: str
    residues: int
    confidence: dict[str, float] = Field(
        description="Mean pLDDT for the structure, from 0 to 100. Above 70 is confident."
    )

@serve
class ProteinFolding:
    requirements = [
        "torch==2.14.1",
        "transformers==5.21.0",
        "accelerate==1.15.0",
    ]

    def load(self) -> None:
        if hasattr(self, "model"):
            return

        # Here and not at the top of the file. The build imports this file with the
        # platform's own dependencies, not yours, so nothing in requirements exists
        # until a worker runs. A `with imports():` block at the top of the file does
        # the same, and is what to use when a name has to be visible outside a method.
        import torch
        from transformers import AutoTokenizer, EsmForProteinFolding

        self.torch = torch
        self.tokenizer = AutoTokenizer.from_pretrained(
            MODEL, revision=REVISION, cache_dir=CACHE
        )
        self.model = EsmForProteinFolding.from_pretrained(
            MODEL, revision=REVISION, cache_dir=CACHE
        )
        self.model = self.model.cuda().eval()
        self.model.trunk.set_chunk_size(CHUNK)

        print(f"warming up: folding {len(WARMUP)} residues", flush=True)
        self._fold(WARMUP)
        print("warmup complete", flush=True)

    def predict(self, request: Request) -> Folded:
        structure, confidence = self._fold(request.sequence)

        return Folded(
            structure=structure,
            format="pdb",
            residues=len(request.sequence),
            confidence=confidence,
        )

    def _fold(self, sequence: str) -> tuple[str, dict[str, float]]:
        tokens = self.tokenizer(
            [sequence], return_tensors="pt", add_special_tokens=False
        )["input_ids"].cuda()

        with self.torch.no_grad():
            output = self.model(tokens)

        # Measured: this model returns pLDDT on a 0 to 1 scale, while the
        # literature and every structure viewer use 0 to 100. Scaled once here,
        # and guarded so a version that already returns 0 to 100 is left alone.
        plddt = float(output["plddt"].mean())

        return self.model.output_to_pdb(output)[0], {
            "mean_plddt": round(plddt * 100 if plddt <= 1.0 else plddt, 2)
        }
```

## Deploying the app

protein-foldingrtx-pro-6000[source](https://github.com/Runware/runware-serverless-examples/tree/main/protein-folding)

[One-click deploy](https://runware.ai/serverless/apps?template=protein-folding)

**From a URL**:

```bash
runware serverless deploy --from https://runware.ai/docs/serverless/examples/protein-folding.zip
```

**From a clone**:

```bash
runware serverless deploy model.py \
  --id protein-folding \
  --gpu-type rtx-pro-6000 \
  --volume /weights
```

The weights are about 2.6GB and the first fold is what pulls them, so `load` does one on a short peptide. The volume keeps them off the checkpoint and out of the next cold start.

`load` prints what it is folding and when it is done. A worker that dies quietly during startup leaves a task pending with no error, and the logs are the only place a reason can appear.

## Work outside the models API

The [models API](https://runware.ai/docs/models-api/introduction) covers image, video, audio and text. A workload outside those four is what this path is for: you bring the weights, the platform brings the hardware.

Nothing in this file is unusual: a protein folding model is loaded, called and returned from exactly like an image model.

## Pinning the weights

`from_pretrained` takes `revision`, and without it you are asking for whatever `main` holds today.

```python
EsmForProteinFolding.from_pretrained(MODEL, revision=REVISION, cache_dir=CACHE)
```

> [!WARNING]
> A moving reference is how you end up with **weights the installed version cannot load**. The failure does not arrive as a bad answer: it arrives as a worker that exits during startup, leaving a task `pending` with no error anywhere except the logs.

## Choosing the transformers port

`fair-esm[esmfold]`, the original package, pulls in OpenFold and wants `nvcc` to build kernels. **A code worker has no toolchain at all**, so that route cannot run here.

The transformers port dropped the OpenFold dependency, which is what lets this run as a code app rather than a container. When a scientific package offers both, check what the install builds before you choose.

## No alignment server

ESMFold predicts from a single sequence. Folding tools that want a multiple sequence alignment reach out to an alignment server, and **an app that calls a third party on every request depends on that third party staying up**.

## Sequence length limits

Attention over the sequence grows with the square of its length, so `max_length` is published and documents the limit.

It does not enforce it. The platform checks the types it published but **not a value constraint**, so an oversized sequence reaches the worker and is refused there, after something has already woken up. Enforcing it is the app's job.

## Calling the app

Use `invoke-async` and poll. A fold is tens of seconds, not milliseconds.

**TypeScript**:

```typescript
import { createClient } from '@runware/sdk'

const client = await createClient({ apiKey: process.env.RUNWARE_API_KEY })

const task = await client.invoke({
  appId: 'protein-folding',
  endpointPath: 'predict',
  payload: {
    request: {
      sequence: 'MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE'
    }
  }
})
```

**Python**:

```python
import asyncio
import os

from runware import Runware

async def main():
    client = Runware(api_key=os.environ["RUNWARE_API_KEY"])
    try:
        task = await client.invoke(
            "protein-folding",
            "predict",
            {
                "request": {
                    "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
                }
            },
        )
    finally:
        await client.close()

asyncio.run(main())
```

**cURL**:

```bash
curl https://api.serverless.runware.ai/v1/apps/protein-folding/invoke-async/predict \
  -H "Authorization: Bearer $RUNWARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "payload": {
      "request": {
        "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
      }
    }
  }'
```

**CLI**:

```bash
cat <<'EOF' | runware serverless apps invoke protein-folding predict -f -
{
  "request": {
    "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
  }
}
EOF
```

**JSON**:

```json
{
  "taskId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "payload": {
    "request": {
      "sequence": "MKTAYIAKQRQISFVKSHFSRQLEERLGLIEVQAPILSRVGDGTQDNLSGCEKAVQVKVKALPDAQFEVVHSLAKWKRQTLGQHDFSAGEGLYTHMKALRPDEDRLSPLHSVYVDQWDWERVMGDGERQFSTLKSTVEAIWAGIKATEAAVSEE"
    }
  }
}
```

The structure comes back as PDB text at `output.predictions[0].structure`. Save it to a `.pdb` file and any molecular viewer will open it.

`confidence.mean_plddt` runs from 0 to 100 and is the model's own estimate of how much to trust what it drew. **Above 70 is confident, below 50 is close to a guess**, so a caller can tell the two apart without reading coordinates.

## What the run cost

<table><tbody><tr><td>Call</td><td>Time</td></tr><tr><td>First call, empty volume: weights plus a warmup fold</td><td><strong>4m36s</strong></td></tr><tr><td>A restart, weights already on the volume</td><td><strong>3m3s</strong></td></tr><tr><td>A warm worker, 154 residues</td><td>1.2s</td></tr><tr><td>A warm worker, 22 residues</td><td>1.3s</td></tr></tbody></table>

**A restart still takes minutes.** The volume saves the download, not the load: 2.6GB still has to reach the GPU and the warmup fold still runs. Keep `--min-workers 1` if a cold caller cannot wait.

Length barely moves the warm number at these sizes, so the fold is mostly fixed cost until the sequence gets long enough for the quadratic term to show.