# Files reference **Page:** kit/files/reference [Download Raw Markdown](./kit/files/reference.md) --- # Files reference Lookup tables for [Hoody Files](/kit/files/). Every route and field is in the [Files API reference](/api/files/). The `--flags` here are startup settings of the Files service in your computer. Change them through its [daemon program command](/kit/daemons/#kit-service-flags). A Kit update or program reset can restore the defaults. ## 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/`, 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](#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 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](/api/files/reading/). | 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": "", "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=` | 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=` 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](/api/files/directories/) 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=` 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 | 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 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`](/api/files/reading/) also apply to `GET /api/v1/files/glob/{path}`. ### 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: `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 `\#`. ## Writing with a mode Accepted values and refusals are in the [file operations API](/api/files/file-operations/). - 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. ## 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 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. ## 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: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. | Flag | Environment variable | Default | Meaning | |---|---|---|---| | `--default-create-owner ` | `HOODY_FILE_MANAGER_DEFAULT_CREATE_OWNER` | `user` | `user`, `user:group`, `uid`, `uid:gid`, or `none`/`off` for the process owner, root | | `--allowed-create-owners ` | `HOODY_FILE_MANAGER_ALLOWED_CREATE_OWNERS` | empty | Owners an `owner=` override may request | ## Backends Connecting (`POST /api/v1/backends/{type}`) and testing are in the [cloud](/api/files/mount/cloud/) and [backends](/api/files/managing-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](#pending-uploads). | | Reads | A path the remote lacks is `404`; an unreachable remote is [`BACKEND_UNREACHABLE`](/api/files/reading/). | | `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](#mount-settings). | | 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](#pending-uploads), then repeat. ## Mount rules - **Count:** at most 100 `active` mounts, else `429` "Maximum mount count (100) reached", with no `code`. [`hoody share`](/foundation/storage/share-local-folder/) 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](/api/files/mount/advanced/#post-apiv1mounts). - **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. ## 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`, `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](/api/files/mount/advanced/#patch-apiv1mountsid) 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. ### Changing mount settings - `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](/api/files/mount/advanced/#patch-apiv1mountsid). ### After a service restart - 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: `; `?backend=` requests and tests `404` `Backend not found: `; 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. ## 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 | - `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](/api/files/mount/advanced/#pending-uploads). ## 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](/api/files/mount/advanced/#post-apiv1mounts)); 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. ## Journal - **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](/api/files/journal/). `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. ## Remote downloads - `?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. ## 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](#remote-downloads) | Resume, check free space, or fetch ranges. |