Skip to content

Running Foundry modules on gateways🔗

Early Access

Foundry module execution on gateways is available as Early Access and is enabled per network. Talk to your Apheris representative to enable it for yours.

A Foundry module is a container image that packages a self-contained step of a data or ML workflow — data validation, preprocessing, inference. Modules are built in the Apheris Foundry and run on Apheris Gateways, where the datasets live and access is governed. They can also run standalone on your own infrastructure — that workflow is described in the Apheris Foundry documentation. This guide covers running modules on gateways with the Apheris CLI.

What a Foundry module is🔗

A module is a container image that exposes a single wrapper entrypoint:

module-run --input <path> --output <path> --config '<json>'
  • --input <path> — read-only directory with the input data for this job
  • --output <path> — writable directory; the module writes all results here
  • --config '<json>' — the job payload, a JSON object with two fields: command, the Foundry module to run (created with the Apheris Foundry SDK and packaged in the image), and args, a string with the same arguments you would pass to that module's CLI

The exit code is the verdict: 0 means success, anything else is a failure. The platform never inspects or rewrites the payload — it is forwarded verbatim to the module.

Running a module on a gateway🔗

Foundry modules are provided as model versions in the Apheris Registry, like any other model — you select the module by ID and version in the job's spec.

Modules run through the same JobSpec interface as any other job. The spec selects the datasets and points at the module; the payload selects the module's task and carries its CLI arguments:

spec.json:

{
    "datasets": ["structure-queries_gateway-1_org-1"],
    "model": { "id": "apheris-cofolding", "version": "0.1.0" }
}

payload.json:

{
    "command": "apheris-openfold3",
    "args": "generate-openfold3-dataset --input /input/queries.yaml --output /tmp/cofolding-output"
}
  • command is the Foundry module, created with the Apheris Foundry SDK — here the OpenFold 3 wrapper from the apheris-cofolding module family.
  • args is the same argument string you would pass to that module's CLI — here, generating a dataset from an input query file.
apheris jobspec create --spec spec.json --payload payload.json --wait

The job runs on exactly one gateway — the one that owns the selected datasets. When the module exits 0, the job completes; a non-zero exit or a rejected invocation fails the job with a readable reason. Logs stay retrievable after the run:

$ apheris jobspec status --job-id <id>
apheris jobspec logs --job-id <id>

Results and inputs🔗

Results leave the gateway only as data artifacts. List and download them like any other artifact:

apheris jobspec artifacts --job-id <id>
apheris artifacts download --artifact-id <artifact-id>

Conversely, a module can read input artifacts that your organisation is entitled to.

Note

A Foundry job runs a single task on a single gateway — not a multi-step workflow. Chaining modules is not supported yet.

NVFlare-based federated jobs are unchanged — modules are an additional way to run computations, not a replacement.