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. The imported data 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:
| Scheme | Source |
|---|---|
s3:// | An S3-compatible object store: s3://<bucket-name>/<object-key> |
http://, https:// | A web URL |
file:// | An inline file from the workflow’s files section |
fuzzball://, fb:// | An object in the cluster object cache: fuzzball://group/<path> or fuzzball://user/<path> |
hf:// | The HuggingFace Hub. huggingface:// is accepted as an alias |
The destination is always a file:// path inside the volume. Fuzzball rejects any other scheme
at workflow submission, including the undocumented local:// that earlier releases silently
accepted.
An hf:// source pulls a repository, or a single file from one, from the HuggingFace Hub
straight into a volume. Use it to stage 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/Qwen2.5-0.5B-Instruct). Canonical single-name repositories such ashf://gpt2are 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:
| Parameter | Description |
|---|---|
| revision | Branch, tag, or commit to pull. Defaults to main. |
| type | Repository kind: model (default), dataset, or space. |
| include | Glob of files to include in a whole-repository download. May be repeated. Supports **, *, and ?. |
| exclude | Glob of files to exclude. Applied after include. May be repeated. |
includeandexcludeapply 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: v4
volumes:
model:
use: ephemeral
size: 20GB
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: 30m
jobs:
list-model:
image:
uri: docker://alpine:latest
mounts:
/models: model
command: [/bin/sh, -c, "ls -laR /models/qwen2.5-0.5b-instruct"]
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 resolves against the Hub at run time. Fuzzball uses the
HuggingFace token, if any, only 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:
use: ephemeral
size: 20GB
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 exampletransformers'from_pretrained("/models/qwen2.5-0.5b-instruct").