Ingress

Ingress is one of the first stages of workflow execution, where any data needed for your workflow is imported to your volume from an outside source. This could be input data for analysis, specific configuration files for applications, or anything else your workflow needs to run. Ingress is typically used in combination with ephemeral volumes, since persistent volumes may already have the necessary data saved on them when the workflow starts.

The ingress source.uri selects where the data comes from by its scheme. Fuzzball supports s3://, http://, https://, file:// (inline files from the workflow’s files section), and hf:// (the HuggingFace Hub). The destination is always a file:// path inside the volume.

An hf:// source pulls a repository — or a single file from one — from the HuggingFace Hub straight into a volume. This is convenient for staging a model, dataset, or space into a volume that your jobs then mount.

The source URI takes the form:

hf://<org>/<repo>[/<path>][?revision=<rev>&type=<repo-type>&include=<glob>&exclude=<glob>]

• <org>/<repo>: the repository identifier as it appears on the Hub (e.g. Qwen/Qwen3.5-0.8B). Canonical single-name repositories (e.g. hf://gpt2) are also accepted.
• <path> (optional): a single file within the repository. When present, only that file is downloaded; when omitted, the whole repository is downloaded.

The longer huggingface:// scheme is accepted as an alias for hf:// anywhere a HuggingFace source is given; hf:// is the canonical form.

The following query parameters refine the download:

include and exclude apply only to whole-repository downloads (when no file <path> is given in the URI). They have no effect when the URI already names a single file.

Public repositories need no credentials. For gated or private repositories — or to avoid anonymous rate limits — create a HuggingFace secret holding a HuggingFace user access token and reference it from the source with secret.

The example below pulls a public model repository into an ephemeral volume and then lists it from a job:

version: v1

volumes:
  model:
    ingress:
      - source:
          uri: hf://Qwen/Qwen3.5-0.8B
          # secret: secret://user/my-hf-token   # required only for gated/private repos
        destination:
          uri: file://qwen3.5-0.8b
        policy:
          timeout:
            execute: 30m

jobs:
  list-model:
    image:
      uri: docker://alpine:latest
    mounts:
      model:
        location: /models
    command: [/bin/sh, -c, "ls -laR /models/qwen3.5-0.8b"]
    resource:
      cpu:
        cores: 1
      memory:
        size: 512MiB

To pull a dataset or space instead of a model, set the type query parameter — for example hf://hexgrad/Kokoro-TTS?type=space ingresses a space repository. To stage only part of a large repository, filter with include/exclude, for example hf://bigscience/bloom?include=*.safetensors&exclude=*.bin.

The HuggingFace source is also available as a first-class option in the Web UI workflow editor: when adding an ingress source, choose HuggingFace and fill in the repository, type, optional file path, revision, include/exclude filters, and an optional HuggingFace secret.

hf:// ingress writes the repository into the volume as an ordinary directory of files (config.json, *.safetensors, tokenizer files, and so on). An inference server can therefore load it directly from that local path — point the server at the mounted directory instead of the Hub repository id, and nothing is resolved against the Hub at run time. The HuggingFace token (if any) is only used during ingress, so the serving job never sees it and needs no network access to the Hub.

The example below ingresses a model and serves it with vLLM straight from the ingressed directory:

version: v4

volumes:
  model:
    name: vllm-model
    ingress:
      - source:
          uri: hf://Qwen/Qwen2.5-0.5B-Instruct
          # secret: secret://user/my-hf-token   # required only for gated/private repos
        destination:
          uri: file://qwen2.5-0.5b-instruct
        policy:
          timeout:
            execute: 1h

services:
  vllm:
    persist: true
    cwd: /models
    image:
      uri: docker://vllm/vllm-openai:latest
    mounts:
      /models:
        volume: model
    env:
      - HF_HUB_OFFLINE=1                      # serve fully offline; the model is already local
      - HF_HOME=/models/.cache/huggingface    # writable cache on the volume (containers run non-root)
    network:
      ports:
        - name: openai-api
          port: 8000
          protocol: tcp
      endpoints:
        - name: openai
          type: path
          port-name: openai-api
          protocol: http
          scope: organization
    readiness-probe:
      tcp-socket:
        port: 8000
      initial-delay-seconds: 60
      period-seconds: 15
      failure-threshold: 60
    resource:
      cpu:
        cores: 8
      memory:
        size: 16GiB
      devices:
        nvidia.com/gpu: 1
    script: |
      #!/bin/sh
      # Point vLLM at the local directory, NOT the Hub repo id, so nothing is fetched at serve time.
      vllm serve /models/qwen2.5-0.5b-instruct \
        --served-model-name qwen2.5-0.5b-instruct \
        --host 0.0.0.0 --port 8000

vLLM requires a GPU, so this example runs only on a GPU-enabled node. The same local-path approach works for any framework that accepts a model directory — for example transformers' from_pretrained("/models/qwen2.5-0.5b-instruct").