Skip to content
Hoody Documentation
Hoody.com
Download Page (.md)

Advanced Backends

Section titled “Advanced Backends”

Hoody’s VFS exposes a set of advanced backends — alias, cache, chunker, combine, hasher, local, memory, and union — alongside the persistent FUSE mount lifecycle that exposes them on disk. Use the endpoints on this page to connect specialized backends, list and inspect mounts, create new persistent mounts, retune VFS cache parameters, and tear mounts down.

All endpoints on this page are served from the container’s files service: https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com.

Mounts

Section titled “Mounts”

Mounts are persistent FUSE filesystems that surface a connected backend on disk. Every mount survives container restarts; to remove one, call the unmount endpoint.

GET /api/v1/mounts

Section titled “GET /api/v1/mounts”

List all mounts. Optionally filter by exact label.

This endpoint takes no path parameters.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
labelquerystringNoFilter mounts by label. Only mounts with this exact label will be returned.
Terminal window
curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/mounts?label=Photos" \
  -H "Authorization: Bearer <token>"

GET /api/v1/mounts/{id}

Section titled “GET /api/v1/mounts/{id}”

Get detailed information about a specific mount, including its VFS cache configuration.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesMount ID.
Terminal window
curl -X GET "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/mounts/mount_550e8400e29b41d4a716446655440000" \
  -H "Authorization: Bearer <token>"

POST /api/v1/mounts

Section titled “POST /api/v1/mounts”

Create a persistent FUSE mount for a connected backend. The mount is automatically persisted and restored on server restart; there is no separate persist flag.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
backend_idstringYes—ID of an existing backend connection.
labelstringNo—Optional human-readable label (e.g., "My NAS", "Photos Backup"). Used by the UI and to filter mounts via GET /api/v1/mounts?label=....
mount_pathstringNo—Path for the mount. If omitted, defaults to /hoody/mounts/mount_{uuid}. Relative paths are resolved under the server’s mount directory (/hoody/mounts/).
vfs_configobjectNo—VFS configuration for performance tuning. See below.

The vfs_config object accepts the following fields:

NameTypeRequiredDefaultDescription
vfs_config.cache_modestringNo"writes"Cache mode. One of off, minimal, writes, full.
vfs_config.cache_max_ageinteger | stringNo3600Maximum time files are cached. Accepts seconds or duration strings like "1h", "30m".
vfs_config.cache_max_sizeinteger | stringNo10737418240Maximum cache size in bytes (default 10GB). Accepts bytes or human-readable strings like "10G", "128M".
vfs_config.dir_cache_timeinteger | stringNo300How long directory listings are cached. Accepts seconds or duration strings like "5m", "1h".
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/mounts" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "b_8f4a2c1e9b3d4a5f6c7e8d9a0b1c2d3e",
    "label": "Photos Backup",
    "vfs_config": {
      "cache_mode": "writes",
      "cache_max_age": 3600,
      "cache_max_size": "10G",
      "dir_cache_time": "5m"
    }
  }'

PATCH /api/v1/mounts/{id}

Section titled “PATCH /api/v1/mounts/{id}”

Update the VFS configuration for an existing mount. Allows changing cache settings, buffer sizes, and other VFS parameters.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesMount ID.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
vfs_configobjectYesVFS configuration parameters.
Terminal window
curl -X PATCH "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/mounts/mount_550e8400e29b41d4a716446655440000" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vfs_config": {
      "cache_mode": "full",
      "cache_max_age": 7200,
      "cache_max_size": "20G",
      "dir_cache_time": "10m"
    }
  }'

DELETE /api/v1/mounts/{id}

Section titled “DELETE /api/v1/mounts/{id}”

Remove a mount and disconnect the FUSE filesystem.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
idpathstringYesMount ID.
Terminal window
curl -X DELETE "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/mounts/mount_550e8400e29b41d4a716446655440000" \
  -H "Authorization: Bearer <token>"

Backends

Section titled “Backends”

Connect specialized backends to expose new filesystem capabilities. Each endpoint returns a backend ID that can later be mounted via POST /api/v1/mounts.

POST /api/v1/backends/alias

Section titled “POST /api/v1/backends/alias”

Alias for an existing remote or local path. Useful for renaming or remapping an existing mount target.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
remotestringYes""Remote or path to alias. Can be "myremote:path/to/dir", "myremote:bucket", "myremote:" or "/local/path".
descriptionstringNo""Description of the remote.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/alias" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "myremote:archive/2023",
    "description": "Aliased view of the 2023 archive directory"
  }'

POST /api/v1/backends/cache

Section titled “POST /api/v1/backends/cache”

Cache a remote locally to speed up reads and reduce API calls against the upstream provider.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
remotestringYes""Remote to cache. Normally should contain a : and a path, e.g. "myremote:path/to/dir", "myremote:bucket", or "myremote:" (not recommended).
descriptionstringNo""Description of the remote.
chunk_clean_intervalintegerNo60How often (in seconds) the cache performs cleanups of the chunk storage.
chunk_no_memorybooleanNofalseDisable the in-memory cache for storing chunks during streaming.
chunk_pathstringNo"/home/user/.cache/hoody-vfs/cache-backend"Directory to cache chunk files.
chunk_sizestringNo"5242880"Size of a chunk. One of "1M", "5M", "10M".
chunk_total_sizestringNo"10737418240"Total size the chunks can take up on the local disk. One of "500M", "1G", "10G".
db_pathstringNo"/home/user/.cache/hoody-vfs/cache-backend"Directory to store file structure metadata DB.
db_purgebooleanNofalseClear all the cached data for this remote on start.
db_wait_timeintegerNo1How long to wait (in seconds) for the DB to be available. 0 is unlimited.
info_ageintegerNo21600How long (in seconds) to cache file structure information. One of 1h, 24h, 48h.
plex_insecurestringNo""Skip all certificate verification when connecting to the Plex server.
plex_passwordstringNo""The password of the Plex user.
plex_tokenstringNo""The plex token for authentication (auto set normally).
plex_urlstringNo""The URL of the Plex server.
plex_usernamestringNo""The username of the Plex user.
read_retriesintegerNo10How many times to retry a read from a cache storage.
rpsintegerNo-1Limits requests per second to the source FS. -1 disables.
tmp_upload_pathstringNo""Directory to keep temporary files until they are uploaded. Specifying a value enables this feature.
tmp_wait_timeintegerNo15How long (in seconds) files should be stored in local cache before being uploaded.
workersintegerNo4How many workers should run in parallel to download chunks.
writesbooleanNofalseCache file data on writes through the FS.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/cache" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "s3remote:media-bucket",
    "description": "Cached view of media bucket",
    "chunk_size": "5M",
    "chunk_total_size": "10G",
    "workers": 8,
    "writes": true
  }'

POST /api/v1/backends/chunker

Section titled “POST /api/v1/backends/chunker”

Transparently chunk and split large files on a remote, with optional per-chunk checksums.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
remotestringYes""Remote to chunk/unchunk. Normally should contain a : and a path.
descriptionstringNo""Description of the remote.
chunk_sizestringNo"2147483648"Files larger than chunk size will be split into chunks.
fail_hardbooleanNofalseChoose how chunker should handle files with missing or invalid chunks.
hash_typestringNo"md5"Hash mode. One of none, md5, sha1, md5all, sha1all, md5quick, sha1quick. All modes but "none" require metadata.
meta_formatstringNo"simplejson"Format of the metadata object or "none".
name_formatstringNo"*.hoody-vfs_chunk.###"String format of chunk file names. Must contain exactly one * and one or more consecutive #.
start_fromintegerNo1Minimum valid chunk number. Usually 0 or 1.
transactionsstringNo"rename"How chunker should handle temporary files during transactions. One of rename, norename, auto.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/chunker" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "s3remote:large-files",
    "description": "Split large uploads into chunks",
    "chunk_size": "5368709120",
    "hash_type": "sha1",
    "transactions": "auto"
  }'

POST /api/v1/backends/combine

Section titled “POST /api/v1/backends/combine”

Combine several remotes into one logical namespace, with each upstream mounted under a subdirectory.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
upstreamsstringYes—Upstreams for combining, in the form dir=remote:path dir2=remote2:path. Embedded spaces can be added using quotes, e.g. "dir=remote:path with space".
descriptionstringNo""Description of the remote.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/combine" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "upstreams": "photos=s3remote:photos videos=s3remote:videos documents=gdrive:Documents",
    "description": "Aggregate photos, videos and documents"
  }'

POST /api/v1/backends/hasher

Section titled “POST /api/v1/backends/hasher”

Compute and cache checksums for an existing remote that does not expose them natively.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
remotestringYes""Remote to cache checksums for (e.g. myRemote:path).
descriptionstringNo""Description of the remote.
auto_sizestringNo"0"Auto-update checksum for files smaller than this size (disabled by default).
hashesstringNo"md5,sha1"Comma separated list of supported checksum types.
max_ageintegerNo0Maximum time (in seconds) to keep checksums in cache. 0 = no cache, -1 = cache forever.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/hasher" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "s3remote:backups",
    "description": "Checksum cache for backups",
    "hashes": "md5,sha1,sha256",
    "max_age": 86400
  }'

POST /api/v1/backends/local

Section titled “POST /api/v1/backends/local”

Expose a local filesystem path with full rclone local semantics.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”

All fields are optional.

NameTypeRequiredDefaultDescription
descriptionstringNo""Description of the remote.
case_insensitivebooleanNofalseForce the filesystem to report itself as case insensitive.
case_sensitivebooleanNofalseForce the filesystem to report itself as case sensitive.
copy_linksbooleanNofalseFollow symlinks and copy the pointed to item.
encodingstringNo"33554434"The encoding for the backend.
linksbooleanNofalseTranslate symlinks to/from regular files with a .hoody-vfslink extension.
no_check_updatedbooleanNofalseDon’t check to see if the files change during upload.
no_clonebooleanNofalseDisable reflink cloning for server-side copies.
no_preallocatebooleanNofalseDisable preallocation of disk space for transferred files.
no_set_modtimebooleanNofalseDisable setting modtime after copying a file.
no_sparsebooleanNofalseDisable sparse files for multi-thread downloads.
nouncbooleanNofalseDisable UNC (long path names) conversion on Windows.
one_file_systembooleanNofalseDon’t cross filesystem boundaries (unix/macOS only).
skip_linksbooleanNofalseDon’t warn about skipped symlinks.
time_typestringNo"0"Set what kind of time is returned. One of mtime, atime, btime, ctime.
unicode_normalizationbooleanNofalseApply unicode NFC normalization to paths and filenames.
zero_size_linksbooleanNofalseAssume the Stat size of links is zero (deprecated).
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/local" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Mount local scratch directory",
    "no_preallocate": true,
    "time_type": "mtime"
  }'

POST /api/v1/backends/memory

Section titled “POST /api/v1/backends/memory”

In-memory object storage. Data is volatile and lost when the container restarts.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
descriptionstringNo""Description of the remote.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/memory" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Ephemeral scratch space"
  }'

POST /api/v1/backends/union

Section titled “POST /api/v1/backends/union”

Merge the contents of several upstreams into a single view, with configurable policies for reads, writes, and searches.

This endpoint takes no path, query, or header parameters.

Request Body

Section titled “Request Body”
NameTypeRequiredDefaultDescription
upstreamsstringYes""List of space separated upstreams, e.g. "upstreama:test/dir upstreamb:" or "\"upstreama:test/space:ro dir\" upstreamb:".
descriptionstringNo""Description of the remote.
action_policystringNo"epall"Policy to choose upstream on ACTION category.
cache_timeintegerNo120Cache time (in seconds) of usage and free space. Only useful when a path preserving policy is used.
create_policystringNo"epmfs"Policy to choose upstream on CREATE category.
min_free_spacestringNo"1073741824"Minimum viable free space for lfs/eplfs policies.
search_policystringNo"ff"Policy to choose upstream on SEARCH category.
Terminal window
curl -X POST "https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/union" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "upstreams": "primary:s3remote:primary secondary:s3remote:secondary",
    "description": "Tiered union with primary preferred",
    "create_policy": "epmfs",
    "search_policy": "ff",
    "min_free_space": "5368709120"
  }'