Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for Hoody Files. Every route and field is in the Files API reference. The --flags here are startup settings of the Files service in your computer. Change them through its daemon program command. A Kit update or program reset can restore the defaults.

The Remote button is in the toolbar on a desktop and the actions bar on a phone. It takes an SFTP, WebDAV, S3 or FTP server, credentials and an optional folder name.

TopicRule
LocationMounted in the service’s mount directory, by default /hoody/mounts/permanent/<name>, and opened at once. S3 opens in the bucket and prefix you gave, which the browser remembers for that folder.
NameUp to 64 ASCII letters, digits, ., _ and -, starting with a letter or digit. Left empty: built from the type and the server’s host name, or from the bucket for S3 without an endpoint.
DisconnectRemoves the folder, keeps the saved connection, and says whether waiting uploads were delivered. If incomplete or unknown, they may still run; unsent files are held as pending uploads.
Saved connectionNot removed by the file manager. Remove it with DELETE /api/v1/backends/{id}, or in the Hub under Files > Storage: close its open folders, choose Remove from the storage row’s menu, then confirm with Remove.
CredentialsSent in request bodies only, never in a URL.
No buttonRemote access is off, or settings keep the file manager out of mounts.

Path-route folder listings sort with sort (name, size, mtime) and order (asc, desc). Folder listings on /api/v1/files/ ignore both. The ?json fields are in the reading API.

RequestReturns
A folder on /api/v1/files/{path, entries: [{name, is_dir, size, modified}], count}
?simplePath route only: one item per line, folders ending in /, sent as text/plain; charset=utf-8. A folder on /api/v1/files/ still returns JSON.
?hashJSON {"hash": "<hex>", "algorithm": "sha256"} on /api/v1/files/; the bare hex digest on the path route.
?base64Path route: encoded text, up to 100 MiB for local or mounted files and 50 MiB for one-off remote files. /api/v1/files/: JSON with base64 and size, up to 50 MiB, including remote files. Larger files receive 413.
?content-type=<type>For local and mounted files: the file with that type (type and subtype; any parameters are dropped), always as an attachment, so a browser downloads it. An invalid type is ignored. A download with ?backend=<id> ignores content-type and is sent inline with the inferred type.
?zip, with no valueThe visible, readable files, recursively; empty folders left out, read errors listed inside. The archive limits apply to local and mounted folders and return 422 ARCHIVE_TOO_LARGE; one-off ?type= ZIPs do not enforce those limits. A remote folder zips through its mount path or one-off ?type= access; GET /api/v1/files/{path}?zip&backend=<id> is 501.

Range works on local files, mounted paths and ?backend= downloads. With ?backend=, several ranges that fit the file, or If-Range, return the whole file (200): check for 206 before joining parts.

LimitDefaultHighest
Matches per file, max_count501,000
Matches in total, max_matches50010,000
Size of a searched file, max_filesize10 MiB100 MiB
Folder depth, max_depth50100
Time, timeout in seconds30120
Files searched50,000fixed
Collected match and context data32 MiBfixed
  • A larger value counts as the highest. Long lines are cut to 4,096 UTF-8 bytes, including a trailing ..., which alone does not set truncated.
  • truncated: true means a limit was reached or the search could not finish, not that more matches exist.
  • no_ignore=true includes what .gitignore (inside a git repository), .ignore and git’s exclude files skip. It and hidden also apply to GET /api/v1/files/glob/{path}.

glob takes one .gitignore-style pattern. It only narrows: ignored files stay out.

PatternSearches
*.goFiles named *.go at any depth
*.{ts,tsx}Files ending in .ts or .tsx
src/**/*.ts.ts files anywhere under src/, including src/ itself
src/*.ts.ts files directly in src/; * does not cross /
/main.gomain.go at the top of the searched folder only
!*_test.goEvery file except test files
!vendor/Every file outside vendor/ folders
  • A non-trailing / matches relative to the searched folder: workspace with glob=src/*.ts finds workspace/src/app.ts.
  • Matching is case-sensitive, even with ignore_case=true.
  • A repeated glob, an unparsable pattern or only spaces is 400. Escape a leading # as \#.

Accepted values and refusals are in the file operations API.

  • A service without put_chmod in the features of GET /api/v1/version ignores ?chmod: read mode in the answer.

  • A new file is never created with broader bits than you asked for.

  • A replaced file keeps its inode and owner. It is first narrowed to what both modes allow, so its old content is readable only under bits both allow; the new content appears under the requested mode. A program that already had it open keeps its access.

  • Uploads, appends and permission changes through the service, by any name of the file, wait for each other; direct writers are not covered.

CaseResult
Changing a path another operation uses, a folder above it or something inside409: retry. WebDAV PUT (including ?touch), DELETE, MKCOL, COPY and MOVE answer 423 Locked.
The path changed during the operation409: retry.
Two changes to one file’s content or attributesBoth run; the last value applied stays, and two appends keep both bodies.
Replacing a fileThe old version stays until the new one arrives in full; a refused or cut-off upload leaves it unchanged. A storage error during the final write can leave partial content.
A copyFor a single file, a source-read failure or cancellation before the final write leaves the destination unchanged; a failed final write can leave partial content. A recursive folder copy can leave files and folders already copied when it fails or is cancelled.
An appendThe body arrives in full first. Refused, cut off or cancelled: unchanged, though a new file may be left empty. A failed write can leave part of the text. Text another program appends meanwhile is kept.
A move across mounts that share no connection (different backends, or custom settings)409 FILE_MOVE_CROSSES_DEVICES from the Files API; 409 PATH_CONFLICT from WebDAV MOVE. Copy, then delete.

?copy_to= and ?move_to= take no backend IDs: mount both providers and copy between mounted paths. Writing to a backend needs a type and OAuth scopes that allow writes.

Mounted contents stay available.

  • /proc, the inside of the folders where services keep credentials and keys, and the service’s own data (file history, thumbnail cache, download and extraction records) are 404 on every route, directly, by symbolic link or through /proc, and left out of listings.
  • The credentials folder itself (/hoody/secrets) can be read, and so can folders above protected locations unless they are inside another hidden location. /proc and the service’s own data folders stay 404, their top folders included. Deleting, renaming, replacing or changing a readable protected folder is 409 “Holds or contains service storage: this path cannot be created, deleted, renamed, replaced or changed”. A missing folder above them can be created.
  • History and thumbnails stay readable through their own routes.

The service runs as root, and new local files and folders belong to user; through ?backend=, the remote’s rules apply.

  • Covered: every new inode: uploads, ?mkdir, touch, appends to a new file, extracted entries, copies, downloads (?download_from) and parent folders created on the way. Overwriting, appending to or moving an existing file never changes its owner.
  • Extraction: keeps ordinary permission bits, without setuid, setgid and sticky; new folders use 755, subject to the umask.
  • Override: with --allow-chown, the /api/v1/files/ routes take ?owner=user, ?owner=user:group or ?owner=uid:gid on PUT uploads, appends, ?mkdir, ?extract, ?download_from, ?copy_to, ?move_to and a PATCH move or rename; a move applies it only to folders it creates. Path and WebDAV requests ignore it.
  • Allowed: the default owner and --allowed-create-owners, never root (uid or gid 0); others are 400 or 403.
  • Fail-closed: checked at start. A failed change is 500 and removes the new item; if that fails, a warning is logged and it can remain, owned by root.
FlagEnvironment variableDefaultMeaning
--default-create-owner <spec>HOODY_FILE_MANAGER_DEFAULT_CREATE_OWNERuseruser, user:group, uid, uid:gid, or none/off for the process owner, root
--allowed-create-owners <csv>HOODY_FILE_MANAGER_ALLOWED_CREATE_OWNERSemptyOwners an owner= override may request

Connecting (POST /api/v1/backends/{type}) and testing are in the cloud and backends APIs.

TopicRule
ResponseCreate names the type vfs_backend_type, lowercase with spaces (google cloud storage). List and detail return no settings but server and user, and name it backend_type.
IDSet by the type and the settings naming the server or account (host, port, user, account or key IDs, bucket-level addresses). The same server reuses its ID, also from earlier versions. Changing set_env or a header list that is not plain name/value pairs keeps the ID only when another setting identifies the account; otherwise it creates a new backend.
CredentialsA new password or key keeps the ID when another setting names the account; an account known only by its credential, such as an API key, gets a new backend, so rotate it with PUT /api/v1/backends/{id}. To change host, user, account or type, delete and connect again.
port1 to 65535, as a number or numeric string. Left out, null or empty: the type’s default. Otherwise 400.
In useWhile a mount of the backend serves or has work, in any status, PUT or a connect with other credentials is 409: delete its mounts, then retry. Also 409 during a delivery.
ReadsA path the remote lacks is 404; an unreachable remote is BACKEND_UNREACHABLE.
backend parameterOnly on GET, PUT except append, DELETE and POST with mkdir; elsewhere 400. Remote backends off: 403.
Local onlyContent search, file search, line ranges and path resolution are 400, such as “grep not supported with remote backends”; history is 400 “Journal queries are not supported for remote backends”.
Refused typescache, crypt, union, alias, chunker, combine, compress, hasher, memory, local: Backend type '...' is not permitted, since a wrapper can be re-pointed at the computer’s own filesystem.
ConnectionsBackends are unlimited; connections used by ?backend= requests and default-settings mounts stop at --remote-max-connections (100) and --remote-max-per-server (10 per host, or per type across accounts without host). Custom mounts have the separate session limit.
TestA 200 can say connected or disconnected. Failures: 400 “Connection test failed: …”; temporary refusals: 409 or 503 with Retry-After.

DELETE /api/v1/backends/{id} with uploads=discard deletes what any of its mounts had not uploaded, earlier mounts included, and the backend’s pending uploads held on the server, even mid-delivery. Deliveries of other backends’ held files to it stop; those stay held. It answers 200 with uploads.discarded, or removed: true on a backend already removed, deleting what it left; 409 UPLOADS_DISCARD_SHARED while a mount of the backend has default settings. When another backend uses or used its shared connection, its ?backend= writes there are not deleted: uploads.discarded is null and the backend is kept. Delete the leftover pending upload, then repeat.

  • Count: at most 100 active mounts, else 429 “Maximum mount count (100) reached”, with no code. hoody share mounts count too.
  • One path, one mount: another mount’s path, even in error, is 409 naming it; two spellings of one path count as the same.
  • Refused paths: outside the mount directory or inside a mount, 400 “Mount path must be under the configured mount directory”; with .., 400 “Mount path must not contain ’..’ components”; holding a file or folder, 409 “Mount path already exists and is not a symlink”; at, in or above a service directory, 400 “Mount path is reserved by the service”.
  • Reserved path: until the mount or backend is deleted, files API and WebDAV changes at the mount path or above it are 409 MOUNT_PATH_RESERVED “This path is reserved for a mount, so nothing was changed.”; files inside are written as usual. After a restart the mount retakes it when its link returns, its backend reconnects or an update repairs it; until then, deleting the path removes only the link.
  • Changed path: a folder moved during a create or delete is taken back: 409 MOUNT_PATH_CHANGED “A directory on the mount path changed while the mount path was being changed; nothing was changed, retry”. Untakeable: 500, and the mount stays.
  • Busy: a DELETE is 409 MOUNT_PATH_IN_USE “A files operation is changing the mount path; nothing was changed, retry” when a files operation is writing at the path, without waiting for it to finish, or when the path cannot be read within 5 seconds. Retry after it finishes. Create refusals are in the mounts API.
  • Removal: a mount or backend DELETE removes only the mount’s link; anything put at the path since stays. A link that cannot go is 500, and the mount stays in error: repeat.
  • uploads=keep: a custom mount uploads for at most 24 hours, less if its files cannot be checked for about a minute or the oldest unsent file is 24 hours old and failing. A default mount no other mount shares waits about 35 seconds in the answer; with another user of the connection, uploads go on through it. A service without mount_delete_uploads in GET /api/v1/version features ignores uploads and keeps.
FieldDefaultAccepted
cache_modewritesoff, minimal, writes, full
cache_max_size10G0 for no limit, or 1 MiB to 9007199254740991 bytes
cache_max_age1hUp to 30 days
read_chunk_size128M1 MiB to 1 GiB
write_back5sWait before a closed file uploads, up to 1 hour
dir_cache_time5mListing cache time, up to 30 days
poll_interval1mChange check interval, up to 30 days
read_onlyfalsetrue refuses writes at the mount path; ?backend= can still write
timeoutunset (5m)Idle transfer time, 1 to 600 seconds
contimeoutunset (1m)Connect time, 1 to 120 seconds
low_level_retriesunset (10)0 to 10
  • Units: a size is bytes, or takes K, M, G or T (either case, powers of 1024, B optional). A duration combines h, m, s, else seconds; no d: 30 days is 720h. Whole numbers only. GET reports bytes and seconds.
  • Long names: vfs_cache_max_size, vfs_cache_max_age, vfs_read_chunk_size, vfs_write_back; both spellings is 400. allow_other and allow_non_empty are accepted only as false.
  • Custom settings: any non-default value gives the mount its own connection and cache, on the supported types only; other types, such as box, onedrive or protondrive, are 400 VFS_CONFIG_UNSUPPORTED_BACKEND. Limits: 100 custom mount sessions, including sessions starting, retiring or finishing uploads (429 DEDICATED_VFS_LIMIT), and 20 GiB of held files (507 PENDING_UPLOADS_LIMIT). An update can need a free session even when fewer than 100 mounts are listed. Close files using older sessions and let pending uploads finish before retrying.
  • Caching reads: cache_mode full caches reads through the mount path, not ?backend= reads. Both default and custom mounts can show cached directory listings until dir_cache_time expires or a supported poll detects the change. The defaults are 5m and 1m, respectively.
  • pending_uploads: the count and bytes recorded for a custom mount, not a live backlog: 0 does not prove writes arrived.
  • PATCH is partial; a default value removes an override, but timeout, contimeout and low_level_retries stay set until the mount is recreated. auto_deliver is saved and has no effect.
  • It can take about 25 seconds and completes if the client disconnects; a repeat answers "message": "No changes" and "remounted": false.
  • A process working inside the mount must cd into it again. From defaults no other mount uses, files open across it may stop working within about two minutes.
  • A mount in error is repaired by a PATCH with vfs_config, even unchanged; “the mount’s process exited; repeat the update to restart it” means repeat it.
  • It also waits for a delivery of the mount’s held files, or its backend’s shared ones, else 409 MOUNT_UPDATE_IN_PROGRESS “a delivery of this mount’s held files is running; retry after it finishes”; ?switch=immediate does not skip this. With a write_back over about 10 seconds, updates are refused until it has passed since the last close.
  • ?switch=immediate skips waiting for files closed before the update. They upload later with the previous settings, so a late upload can replace a newer write made through the new settings; let uploads finish instead when you can.
  • Other waits and every error code are in the mounts API.
  • Backends reconnect on their own; default-settings mounts come back active, or error “backend unavailable” until then.
  • Custom mounts come back error “the mount has settings of its own and was not started after the restart; update it to start it”: PATCH their vfs_config.
  • Running uploads and open files carry on, unless their mount cannot be identified.
  • A backend those uploads may still write to stays unconnected. Meanwhile: mount create 404 BACKEND_NOT_FOUND Backend not found: <id>; ?backend= requests and tests 404 Backend not found: <id>; mount updates 409 MOUNT_BACKEND_UNAVAILABLE; a connect 409 with Retry-After: 5, “N files from before the restart are still uploading (last error: …); retry after they finish” or “uploads from before the restart could not be checked yet; retry”.
  • Those uploads end a second after their last file, with the old upload, within a minute if their files cannot be checked, once the oldest unsent file is 24 hours old and failing, or after 24 hours regardless. Unsent files are held. Then reconnect and PATCH each custom mount.

A pending upload is the files one mount could not upload during one run of it (a mount session), held on the server until delivered or discarded; nothing expires. Without remote access, every route is 403.

ActionRoute
List, then list one’s filesGET /api/v1/pending-uploads, GET /api/v1/pending-uploads/{id}/files
Download a held fileGET /api/v1/pending-uploads/{id}/file?path=
Deliver to a backendPOST /api/v1/pending-uploads/{id}/deliver
Stop a running upload, keeping its filesPOST /api/v1/pending-uploads/{id}/stop
Discard every held fileDELETE /api/v1/pending-uploads/{id}, 204: the only copy; cannot be undone
  • deliverable says whether a delivery with the saved settings can start now. A complete: false file may have zero-filled ranges: download or discard it; delivery skips it.
  • Delivery overwrites newer versions on the backend: ask the data’s owner first.
  • An unreadable or damaged record (GET /api/v1/pending-uploads/unreadable) is not a pending upload. While one exists, no mount or backend DELETE can confirm its uploads (delivered: false, discarded: null, backend kept). DELETE /api/v1/pending-uploads/unreadable/{id} deletes it with every file it held, which may be the only copy of changes that never reached the backend; the backend is unchanged (204). It cannot be undone.

Routes, options and errors: pending uploads API.

Mounts need the service’s own storage private. While that check fails, mount and backend requests, files requests with backend and one-off ?type= access are 503 MOUNT_STORAGE_UNAVAILABLE with Retry-After: 30 (details); other requests and both lists still answer. Started during a failure, the list shows default mounts as error “mounts are unavailable until the server’s storage check passes”.

  • The message names /hoody/secrets/hoody-files/vfs or /run/hoody-files/vfs and why, such as ancestor "/hoody/secrets" has mode 775; it must not be group- or other-writable.
  • Fix: every directory above owned by root, not writable by group or others; the directory owned by the service’s user, mode 0700. Retry; no restart needed.
  • Settings: --journal-path turns recording on; --allow-journal opens the read routes; a Hoody computer sets both. Without them: 403 “Journal query access not enabled. Use —allow-journal flag.” or 404 “Journal is not enabled”. -A does not include --allow-journal.
  • Best effort: journaling errors never fail file operations.
  • Build folders: journal-ignore-dev-dirs (on) skips build and dependency folders at any depth, including node_modules, .next, .venv, venv, env, target, vendor, deps, obj, _build, dist, build, out, coverage, .cache, .svn, __pycache__, .gradle and .terraform; --no-journal-ignore-dev-dirs tracks them.
  • Limits: journal-max-file-size (2 MiB), journal-max-days (90), journal-max-storage (2 GiB); over budget, new entries can be dropped.
  • Answers: missing revision 404; recorded delete or move 410; content unavailable 422; private data 404. Paging and 503 are in the journal API. complete: false means gaps.
  • Diffs are cut at journal-max-file-size, still 200, with X-Truncated: true. Time reads cannot see missed or outside changes.
  • ?download and ?download_from stop at 100 GiB or 12 hours; timeout is clamped to 12 hours, the default. Past the size cap the partial file is deleted; split large jobs.
  • HTTPS also trusts the computer’s own certificate store, not only public roots.
SymptomCauseFix
Connect or test failsExpired token, invalid key, mismatched client ID and secret, wrong S3 regionFix the credentials, then test. Drive needs OAuth scopes such as drive.readonly; Dropbox tokens have app-specific permissions.
404 for an existing fileWrong case in the path, or a wrong backend IDList the folder with ?json, and GET /api/v1/backends.
Hash mismatchIncomplete download, a change meanwhile, corruption, another algorithmDownload again; verify SHA-256. Resume (curl -C -) only an unchanged source.
429A service concurrency limit, or provider throttling (not always 429)Wait for running operations; for a provider, space requests, batch, or cache through a mount.
Large download failsTimeout, full disk, or the capsResume, check free space, or fetch ranges.