Object Cache
The Fuzzball Object Cache is a built-in store for sharing files, data, and container
images across workflows and
clusters. Objects are addressed with fb:// URIs, organized into group and user
namespaces, and managed through the fuzzball object commands or the web UI. Objects can
be given a time-to-live (TTL) so the cache cleans up old data automatically.
The object cache is also used transparently to speed up container image pulls — see Automatic SIF image caching below.
Objects are referenced with an fb:// URI (the fuzzball:// prefix is also accepted):
fb://group/path/to/object
fb://user/path/to/object
There are two namespaces:
fb://group/...— objects shared within your currently selected group. Visible to members of the group.fb://user/...— objects private to your user. Objects placed in the user namespace are keyed to your user and do not appear in the group listing, and vice versa.
A reference may be pinned to a specific content digest:
fb://group/images/myapp.sif@sha256:abc123...
The fuzzball object command group manages cached objects.
$ fuzzball object put ./report.csv fb://group/reports/report.csv| Flag | Description |
|---|---|
--ttl | TTL duration for the object (e.g., 7d, 24h, 30d) |
--recursive, -R | Recursively upload all files in a directory |
$ fuzzball object put ./dataset fb://user/datasets/run1 --recursive --ttl 7dIf the destination URI omits the object name (it ends in a trailing slash, such
as fb://group/), the name is inferred from the source basename. The following
two commands are equivalent:
$ fuzzball object put ./report.csv fb://group/
$ fuzzball object put ./report.csv fb://group/report.csvThe same applies recursively — fuzzball object put -R ./dataset fb://group/
uploads the tree under fb://group/dataset/.
$ fuzzball object get fb://group/reports/report.csv ./report.csv| Flag | Description |
|---|---|
--recursive, -R | Recursively download all objects under a prefix |
If the local destination names a directory (it ends in a trailing slash, or is
. / ..), the name is inferred from the object basename. The following two
commands are equivalent:
$ fuzzball object get fb://group/reports/report.csv ./
$ fuzzball object get fb://group/reports/report.csv ./report.csvThe same applies recursively — fuzzball object get -R fb://group/dataset ./
downloads the tree into ./dataset/.
$ fuzzball object list fb://group/reportsThe CLI walks every page automatically and prints the full result set.
| Flag | Description |
|---|---|
--versions | Include version history for each object |
--page-size, -p | Server batch size per request (does not cap total results) |
--max-pages, -m | Hard cap on pages fetched (0 = no cap) |
$ fuzzball object describe fb://group/reports/report.csvShows detailed information about an object, including its size, digest, and versions.
$ fuzzball object delete fb://group/reports/report.csv| Flag | Description |
|---|---|
--force, -f | Skip the confirmation prompt |
When a workflow pulls an external container image — for example via a docker:// or
oras:// URI — Fuzzball converts the image to the SIF format and caches the result in
the object cache automatically. Subsequent pulls of the same image are served from the
cache instead of the external registry, which speeds up workflow startup and reduces
dependence on external registry availability.
No configuration is required to benefit from this behavior.
The Fuzzball web UI includes an Object Cache browser for uploading, searching, and inspecting objects across the group and user namespaces, including object metadata and version history.