Share a local folder reference
Section titled “Share a local folder reference”Lookup for hoody share; the guide covers everyday use.
Commands and options
Section titled “Commands and options”hoody share <dir> [--name <name>] [--read-only] [--computer <id>] [--rclone <path>] [--drain-timeout <s>]hoody share list [-o json]hoody share stop <name> [--computer <id>] [--force] [-o json]| Option | Meaning |
|---|---|
--name <name> | Folder’s name in the computer. Default: base name of the resolved folder path; if <dir> is a symbolic link, this uses the target folder’s name |
--read-only | Refuses every write, in the computer and, through rclone, from any client of the share’s URL |
--computer <id> | Without it, a share uses global -c <id>, then HOODY_COMPUTER or your configured default, or refuses to start. stop reads only this or -c <id>, so a default never hides a same-named share elsewhere |
--rclone <path> | rclone binary to run. Default: rclone on your PATH |
--drain-timeout <s> | hoody share <dir> only. Longest stop wait, in whole seconds. Default: 300 |
--force | stop only. Discards undelivered writes instead of waiting |
-o json | list and stop: print JSON |
Requirements
Section titled “Requirements”An older rclone is refused at start, and an older files kit before anything is created. The share uses the computer’s files and tunnel kits. Commands accept Windows paths, but Windows is not supported. Over the SSH gateway every hoody share command exits with status 2.
brew install rclone # macOSapt install rclone # Linux; or: dnf install rclonethe files kit of computer <id> is too old for hoody share: its mount DELETE cannot wait for the mount's uploads. Update the computer's files kit, then share againshare is not available over the SSH gateway. Run hoody on your own machine to use it.--rclone is not available over the SSH gateway. Run hoody on your own machine to use it.Folder and name rules
Section titled “Folder and name rules”| Case | Rule |
|---|---|
<dir> | Must be an existing folder |
Folder called list or stop | Write its path: hoody share ./list |
Colon before the first / (Linux, macOS) | notes:2026 is refused because rclone would read it as a remote. Write ./notes:2026 |
| Name | 1 to 64 characters; letters, digits, ., _, -; not . or ..; not starting with - |
| Base name breaks a rule | Use --name. The refusal states the rule |
| Mount already at the path | The files kit’s error asks whether something is mounted there. Pick another --name |
share name "<name>" is not allowed: use 1-64 characters from A-Z a-z 0-9 . _ -, not "." or "..", and not starting with "-". Example: --name <suggested name>"<name>" is already shared to computer <id> by a running hoody shareThe suggested name replaces each run of invalid characters with -, removes leading hyphens, then truncates to 64 characters. It is my-folder if the result is empty, . or ... When output is not a terminal, both lines start with ✗ .
Start-up output
Section titled “Start-up output”Quoted messages on this page are the form printed when output is not a terminal: a pipe, CI or HOODY_AGENT_MODE=1. The one exception is the second block below, which is the terminal form: on stderr, after a line naming the computer and the share, as timestamped lines. A share that does not come up prints no line naming the computer: the lines so far, such as Sharing …, then one ✕ sentence.
✓ <folder> is shared In the computer: <path> Through: <host>
Press Ctrl+C to stop, or run `hoody share stop <name> --computer <id>`.Sharing <dir> into computer <id>…<folder> is sharedin the computer <path>through <host>ctrl-c stops, or run hoody share stop <name> --computer <id>Reads and writes
Section titled “Reads and writes”| Topic | Behaviour |
|---|---|
| Write success | Reported once saved in the computer, by hoody-files’ normal write cache |
| File held open for writing | A log, for example, can stay unsent until closed |
| Program types | Any, including in-place changes (SQLite, editors, appended logs), renames, temp-file-then-rename |
| File contents | Read from your local machine; speed depends on the connection. Listings are not cached. Reading a read-only share copies nothing into the computer’s storage unless your program does |
| Symbolic links | Not followed or forwarded, so absent in the computer |
| Accepted write, then offline | May still be cached: success does not mean delivered. Let the stop wait confirm |
| Last save | Writes are not checked against local changes. A computer write counts as saved when it reaches your local machine |
Reconnecting
Section titled “Reconnecting”While offline, the mount stays, listed as active. The share first tries to resume its tunnel session.
| Case | What happens |
|---|---|
| Closed connection | Noticed at once; session kept about a minute. Back within it: resumed, same URL |
| Silent drop (sleep, lost network) | Noticed after up to about 2.5 minutes; until then a resume is refused and the port held. The share retries, resuming within the minute after |
| Away longer | The share binds the same computer port once released: same URL |
| Files kit or computer restarts | The share checks its mount every 30 seconds and tries to restart it with its original settings. A removed mount or other error is reported, not recreated |
Connection and credentials
Section titled “Connection and credentials”rclone serves WebDAV on your local machine’s loopback address. A hoody-tunnel binding publishes it over HTTPS on the computer’s domain, and hoody-files mounts that. Your local machine opens the tunnel and accepts no inbound connection.
Each share gets its own URL and random user name and password; the URL refuses requests without them. The CLI writes the user name to its local record, but never prints, stores or puts the password on a command line. Only rclone and hoody-files receive the password, which hoody-files stores like any storage backend credential; you never need it. The address stays open until you stop the share.
hoody share list
Section titled “hoody share list”Shares your user account on this local machine started and has not cleaned up, across all computers. Columns: NAME, STATUS, COMPUTER, PATH (in the computer), LOCAL. A terminal fits them to its width, heads status STATE and puts computer id last.
| Status | Meaning |
|---|---|
starting, serving, reconnecting, stopping | The command is running, in that state |
dead | The command is gone and the share was not cleaned up |
cleanup pending | Stopped, but something in the computer could not be removed, or some writes had not arrived |
How a stop works
Section titled “How a stop works”A stop starts from Ctrl+C, hoody share stop <name> (same wait and progress), or rclone exiting. During the wait the share keeps serving and reconnecting. Once hoody-files confirms delivery and removes the mount, the share removes the backend, closes the tunnel and stops rclone.
A wait ending unconfirmed (timeout, second Ctrl+C, error) keeps the writes and backend in the computer, and the mount unless already removed. The tunnel closes and rclone stops, so nothing more is delivered: cleanup pending, exit 1.
What a stop can print:
Stopping: waiting for the computer to send its writes here (Ctrl+C again to stop without waiting).waiting for 3 files not yet on this machine, 1 still open in the computer (up to 280 s more)removing the mount once the computer has sent what it still holds (up to 270 s)! stopping without waiting; what the computer has not sent yet stays there! stopping with 3 files not yet on this machine; they stay in the computer (`hoody share stop photos --force` discards them)! the computer did not send everything in time: it still holds 3 files not yet on this machineLast line in the share’s terminal:
| Output | Meaning | Exit |
|---|---|---|
✓ stopped: everything written in the computer is on this machine, and <path> is gone from the computer | Delivery confirmed, mount removed. If rclone exited or a conflict ended the share, ✗ <reason> follows as the last line, exit 1 | 0 |
✗ stopped, but the computer never confirmed it had sent everything here: a write made there may not have reached this machine | Nothing left in the computer, but unconfirmed, for example mount and backend removed another way | 1 |
! stopped by `hoody share stop --force`: what the computer had not sent here was discarded | Another terminal ran stop --force | 1 |
✗ stopped, but cleanup is pending: <what is left> | A mount holding undelivered writes, an unconfirmed backend, or an unremovable resource. The next line gives the finishing command, with --force if needed | 1 |
Stop cases
Section titled “Stop cases”| Case | Result |
|---|---|
hoody share stop, clean | ✓ stopped <name> (computer <id>) (on a terminal, a ✓ line naming the share), exit 0. Otherwise ✗ with the reason, exit 1 |
--force, running share | Discards unsent writes; open files give errors; removes mount and backend. Same ✓ line, exit 0 |
| Name on several computers | "<name>" is shared to more than one computer; pass --computer with one of: and one command per computer, exit 2 |
Ctrl+C in a stop terminal | ! stopped waiting; `hoody share list` shows what is left; run `hoody share stop <name>` again to finish it (it says if --force is needed), exit 130. A running share goes on stopping; otherwise cleanup stays recorded |
| rclone exited | No wait; held writes stay |
Mount removed outside hoody share | Backend kept, cleanup pending. Only --force finishes, discarding unsent writes |
| Computer unreachable | A running share, or stop --force, records cleanup pending: run stop again once the computer is reachable. A dead share’s plain stop refuses (exit 1), because the computer cannot say what it holds: run it again once the computer is reachable, or add --force to discard unsent writes |
| Another local user | Cannot stop your share |
Cleanup
Section titled “Cleanup”✗ share "photos" is not running, and the computer holds 3 files that never reached this machine. They cannot be delivered, and stopping discards them: run `hoody share stop photos --force` to discard them| Case | Behaviour |
|---|---|
stop on a dead share | Stops leftover rclone, removes the mount, waits up to 10 seconds for confirmation. Unconfirmed: backend stays, cleanup pending |
stop refuses, exit 1 | The computer holds writes or cannot say, or a mount was removed before confirmation (interrupted stop, files API). The pending uploads API may omit writes held by the active mount, but can list writes left after a computer restart while the restored mount still exists; see the guide before --force |
--force | The computer deletes the writes; the backend goes once confirmed. Otherwise cleanup pending: run it again. Same for a stop that ended early |
Limits
Section titled “Limits”| Limit | Detail |
|---|---|
| Foreground only | No background mode yet |
| Computer restart during uploads | Those writes stay in the computer, not delivered automatically |
| One local machine per mount | Several local machines cannot share into the same mount path in a computer |
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| I/O error in the computer | Local machine asleep or offline, or command stopped | Running: wait for reconnect, rewrite failures. Stopped: held writes can no longer be delivered, and stop asks for --force before discarding them; then share again |
| Computer change not local yet | Delivery takes seconds, or you went offline | Wait. If offline, keep sharing until reconnected |
Permission denied as user | Needs sudo | Use sudo or root |
| No computer specified | None found | Pass --computer <id> or -c <id>, or set HOODY_COMPUTER |
| rclone not found or too old | Below v1.61.0, or cannot run | Install or update, or use --rclone |
an earlier share of "<name>" was not cleaned up: run `hoody share stop <name>` | Earlier same-named share | stop, adding --force if it reports unsent writes |
the files kit of computer <id> is too old to discard what a removed mount or backend left; update it, then run `hoody share stop <name> --force` again | Kit cannot discard writes left by a gone mount or backend; stays cleanup pending | Update the kit, rerun |
--force always leaves cleanup pending | A damaged or unreadable upload record blocks every share stop on that computer | Delete records (below) until the list is empty, then rerun. See unreadable records |
conflict: computer port <port> has been held by another tunnel binding for 300 s; the share does not evict it | Another binding kept the port for five minutes; held writes stay, cleanup pending | stop (--force discards them), share again |
conflict: the tunnel came back on another URL | Reconnected without the original URL; same result | Same |
An unreadable record may read again, so try --force again first. Deleting a record also deletes every unsent file it held, possibly the only copy, and cannot be undone.
# List the recordshoody files uploads unreadable list -c "$COMPUTER_ID"
# Delete onehoody files uploads unreadable delete "$RECORD_ID" -c "$COMPUTER_ID"import { HoodyClient } from 'hoody-sdk';
const hoody = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN });const box = await hoody.withComputer({ id: COMPUTER_ID, project_id: PROJECT_ID, server: SERVER });
// List the recordsconst records = await box.files.uploads.listUnreadable();
// Delete oneawait box.files.uploads.deleteUnreadable(RECORD_ID);# List the recordscurl "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/unreadable"
# Delete onecurl -X DELETE "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/unreadable/$RECORD_ID"Replace the IDs before clicking. The second link deletes the record for good.
# List the recordshttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-files-1.SERVER.computers.hoody.com/api/v1/pending-uploads/unreadable&method=GET&response=transparent
# Delete onehttps://PROJECT_ID-COMPUTER_ID-curl-1.SERVER.computers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-COMPUTER_ID-files-1.SERVER.computers.hoody.com/api/v1/pending-uploads/unreadable/RECORD_ID&method=DELETE&response=transparentOne request, one link
cURL runs inside your computer and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.
Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials. It also appears in the cURL service's request log, not only the target's. Prefer a delegated token with minimal permissions and an expiry: see API tokens.
Slashes, colons and braces pass through as they are. The one character you must
encode is an & inside a value, which happens when the wrapped URL
carries its own query string. Left raw it ends the value early, and the rest is
read as cURL's own parameters, so you get a 200 on a request you did
not make.
How the wrapping works Chaining calls into one link Turning a link into a shortcut
{"success": true, "message": "Unreadable pending uploads", "data": [{"id": "3f0c9a1e2b7d4c5a8e6f1b2c3d4e5f60", "size": 1048576, "reason": "damaged"}]}