Files reference
Section titled “Files reference”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.
Remote folders
Section titled “Remote folders”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.
| Topic | Rule |
|---|---|
| Location | Mounted 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. |
| Name | Up 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. |
| Disconnect | Removes 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 connection | Not 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. |
| Credentials | Sent in request bodies only, never in a URL. |
| No button | Remote access is off, or settings keep the file manager out of mounts. |
Response formats
Section titled “Response formats”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.
| Request | Returns |
|---|---|
A folder on /api/v1/files/ | {path, entries: [{name, is_dir, size, modified}], count} |
?simple | Path 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. |
?hash | JSON {"hash": "<hex>", "algorithm": "sha256"} on /api/v1/files/; the bare hex digest on the path route. |
?base64 | Path 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 value | The 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.
Search limits
Section titled “Search limits”| Limit | Default | Highest |
|---|---|---|
Matches per file, max_count | 50 | 1,000 |
Matches in total, max_matches | 500 | 10,000 |
Size of a searched file, max_filesize | 10 MiB | 100 MiB |
Folder depth, max_depth | 50 | 100 |
Time, timeout in seconds | 30 | 120 |
| Files searched | 50,000 | fixed |
| Collected match and context data | 32 MiB | fixed |
- A larger value counts as the highest. Long lines are cut to 4,096 UTF-8 bytes, including a trailing
..., which alone does not settruncated. truncated: truemeans a limit was reached or the search could not finish, not that more matches exist.no_ignore=trueincludes what.gitignore(inside a git repository),.ignoreand git’s exclude files skip. It andhiddenalso apply toGET /api/v1/files/glob/{path}.
Glob patterns
Section titled “Glob patterns”glob takes one .gitignore-style pattern. It only narrows: ignored files stay out.
| Pattern | Searches |
|---|---|
*.go | Files 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.go | main.go at the top of the searched folder only |
!*_test.go | Every file except test files |
!vendor/ | Every file outside vendor/ folders |
- A non-trailing
/matches relative to the searched folder:workspacewithglob=src/*.tsfindsworkspace/src/app.ts. - Matching is case-sensitive, even with
ignore_case=true. - A repeated
glob, an unparsable pattern or only spaces is400. Escape a leading#as\#.
Writing with a mode
Section titled “Writing with a mode”Accepted values and refusals are in the file operations API.
-
A service without
put_chmodin thefeaturesofGET /api/v1/versionignores?chmod: readmodein 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.
Writes and conflicts
Section titled “Writes and conflicts”| Case | Result |
|---|---|
| Changing a path another operation uses, a folder above it or something inside | 409: retry. WebDAV PUT (including ?touch), DELETE, MKCOL, COPY and MOVE answer 423 Locked. |
| The path changed during the operation | 409: retry. |
| Two changes to one file’s content or attributes | Both run; the last value applied stays, and two appends keep both bodies. |
| Replacing a file | The 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 copy | For 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 append | The 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.
Protected locations
Section titled “Protected locations”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) are404on 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./procand the service’s own data folders stay404, their top folders included. Deleting, renaming, replacing or changing a readable protected folder is409“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.
File ownership
Section titled “File ownership”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:groupor?owner=uid:gidonPUTuploads, appends,?mkdir,?extract,?download_from,?copy_to,?move_toand aPATCHmove 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, neverroot(uid or gid0); others are400or403. - Fail-closed: checked at start. A failed change is
500and removes the new item; if that fails, a warning is logged and it can remain, owned by root.
| Flag | Environment variable | Default | Meaning |
|---|---|---|---|
--default-create-owner <spec> | HOODY_FILE_MANAGER_DEFAULT_CREATE_OWNER | user | user, user:group, uid, uid:gid, or none/off for the process owner, root |
--allowed-create-owners <csv> | HOODY_FILE_MANAGER_ALLOWED_CREATE_OWNERS | empty | Owners an owner= override may request |
Backends
Section titled “Backends”Connecting (POST /api/v1/backends/{type}) and testing are in the cloud and backends APIs.
| Topic | Rule |
|---|---|
| Response | Create 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. |
| ID | Set 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. |
| Credentials | A 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. |
port | 1 to 65535, as a number or numeric string. Left out, null or empty: the type’s default. Otherwise 400. |
| In use | While 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. |
| Reads | A path the remote lacks is 404; an unreachable remote is BACKEND_UNREACHABLE. |
backend parameter | Only on GET, PUT except append, DELETE and POST with mkdir; elsewhere 400. Remote backends off: 403. |
| Local only | Content 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 types | cache, 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. |
| Connections | Backends 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. |
| Test | A 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.
Mount rules
Section titled “Mount rules”- Count: at most 100
activemounts, else429“Maximum mount count (100) reached”, with nocode.hoody sharemounts count too. - One path, one mount: another mount’s path, even in
error, is409naming 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
409MOUNT_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:
409MOUNT_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
DELETEis409MOUNT_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
DELETEremoves only the mount’s link; anything put at the path since stays. A link that cannot go is500, and the mount stays inerror: 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 withoutmount_delete_uploadsinGET /api/v1/versionfeaturesignoresuploadsand keeps.
Mount settings
Section titled “Mount settings”| Field | Default | Accepted |
|---|---|---|
cache_mode | writes | off, minimal, writes, full |
cache_max_size | 10G | 0 for no limit, or 1 MiB to 9007199254740991 bytes |
cache_max_age | 1h | Up to 30 days |
read_chunk_size | 128M | 1 MiB to 1 GiB |
write_back | 5s | Wait before a closed file uploads, up to 1 hour |
dir_cache_time | 5m | Listing cache time, up to 30 days |
poll_interval | 1m | Change check interval, up to 30 days |
read_only | false | true refuses writes at the mount path; ?backend= can still write |
timeout | unset (5m) | Idle transfer time, 1 to 600 seconds |
contimeout | unset (1m) | Connect time, 1 to 120 seconds |
low_level_retries | unset (10) | 0 to 10 |
- Units: a size is bytes, or takes
K,M,GorT(either case, powers of 1024,Boptional). A duration combinesh,m,s, else seconds; nod: 30 days is720h. Whole numbers only.GETreports bytes and seconds. - Long names:
vfs_cache_max_size,vfs_cache_max_age,vfs_read_chunk_size,vfs_write_back; both spellings is400.allow_otherandallow_non_emptyare accepted only asfalse. - Custom settings: any non-default value gives the mount its own connection and cache, on the supported types only; other types, such as
box,onedriveorprotondrive, are400VFS_CONFIG_UNSUPPORTED_BACKEND. Limits: 100 custom mount sessions, including sessions starting, retiring or finishing uploads (429DEDICATED_VFS_LIMIT), and 20 GiB of held files (507PENDING_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_modefullcaches reads through the mount path, not?backend=reads. Both default and custom mounts can show cached directory listings untildir_cache_timeexpires or a supported poll detects the change. The defaults are5mand1m, respectively. pending_uploads: thecountandbytesrecorded for a custom mount, not a live backlog:0does not prove writes arrived.
Changing mount settings
Section titled “Changing mount settings”PATCHis partial; a default value removes an override, buttimeout,contimeoutandlow_level_retriesstay set until the mount is recreated.auto_deliveris 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
cdinto it again. From defaults no other mount uses, files open across it may stop working within about two minutes. - A mount in
erroris repaired by aPATCHwithvfs_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
409MOUNT_UPDATE_IN_PROGRESS“a delivery of this mount’s held files is running; retry after it finishes”;?switch=immediatedoes not skip this. With awrite_backover about 10 seconds, updates are refused until it has passed since the last close. ?switch=immediateskips 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.
After a service restart
Section titled “After a service restart”- Backends reconnect on their own; default-settings mounts come back
active, orerror“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”:PATCHtheirvfs_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
404BACKEND_NOT_FOUNDBackend not found: <id>;?backend=requests and tests404Backend not found: <id>; mount updates409MOUNT_BACKEND_UNAVAILABLE; a connect409withRetry-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
PATCHeach custom mount.
Pending uploads
Section titled “Pending uploads”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.
| Action | Route |
|---|---|
| List, then list one’s files | GET /api/v1/pending-uploads, GET /api/v1/pending-uploads/{id}/files |
| Download a held file | GET /api/v1/pending-uploads/{id}/file?path= |
| Deliver to a backend | POST /api/v1/pending-uploads/{id}/deliver |
| Stop a running upload, keeping its files | POST /api/v1/pending-uploads/{id}/stop |
| Discard every held file | DELETE /api/v1/pending-uploads/{id}, 204: the only copy; cannot be undone |
deliverablesays whether a delivery with the saved settings can start now. Acomplete: falsefile 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
unreadableordamagedrecord (GET /api/v1/pending-uploads/unreadable) is not a pending upload. While one exists, no mount or backendDELETEcan 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.
Storage check
Section titled “Storage check”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/vfsor/run/hoody-files/vfsand why, such asancestor "/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.
Journal
Section titled “Journal”- Settings:
--journal-pathturns recording on;--allow-journalopens the read routes; a Hoody computer sets both. Without them:403“Journal query access not enabled. Use —allow-journal flag.” or404“Journal is not enabled”.-Adoes 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, includingnode_modules,.next,.venv,venv,env,target,vendor,deps,obj,_build,dist,build,out,coverage,.cache,.svn,__pycache__,.gradleand.terraform;--no-journal-ignore-dev-dirstracks 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 move410; content unavailable422; private data404. Paging and503are in the journal API.complete: falsemeans gaps. - Diffs are cut at
journal-max-file-size, still200, withX-Truncated: true. Time reads cannot see missed or outside changes.
Remote downloads
Section titled “Remote downloads”?downloadand?download_fromstop at 100 GiB or 12 hours;timeoutis 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.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| Connect or test fails | Expired token, invalid key, mismatched client ID and secret, wrong S3 region | Fix the credentials, then test. Drive needs OAuth scopes such as drive.readonly; Dropbox tokens have app-specific permissions. |
404 for an existing file | Wrong case in the path, or a wrong backend ID | List the folder with ?json, and GET /api/v1/backends. |
| Hash mismatch | Incomplete download, a change meanwhile, corruption, another algorithm | Download again; verify SHA-256. Resume (curl -C -) only an unchanged source. |
429 | A 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 fails | Timeout, full disk, or the caps | Resume, check free space, or fetch ranges. |