Skip to content

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

Hoody.com

Lookup for hoody share; the guide covers everyday use.

Terminal window
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]
OptionMeaning
--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-onlyRefuses 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
--forcestop only. Discards undelivered writes instead of waiting
-o jsonlist and stop: print JSON

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.

Terminal window
brew install rclone # macOS
apt install rclone # Linux; or: dnf install rclone
the 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 again
share 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.
CaseRule
<dir>Must be an existing folder
Folder called list or stopWrite 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
Name1 to 64 characters; letters, digits, ., _, -; not . or ..; not starting with -
Base name breaks a ruleUse --name. The refusal states the rule
Mount already at the pathThe 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 share

The 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 ✗ .

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 shared
in the computer <path>
through <host>
ctrl-c stops, or run hoody share stop <name> --computer <id>
TopicBehaviour
Write successReported once saved in the computer, by hoody-files’ normal write cache
File held open for writingA log, for example, can stay unsent until closed
Program typesAny, including in-place changes (SQLite, editors, appended logs), renames, temp-file-then-rename
File contentsRead 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 linksNot followed or forwarded, so absent in the computer
Accepted write, then offlineMay still be cached: success does not mean delivered. Let the stop wait confirm
Last saveWrites are not checked against local changes. A computer write counts as saved when it reaches your local machine

While offline, the mount stays, listed as active. The share first tries to resume its tunnel session.

CaseWhat happens
Closed connectionNoticed 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 longerThe share binds the same computer port once released: same URL
Files kit or computer restartsThe 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

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.

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.

StatusMeaning
starting, serving, reconnecting, stoppingThe command is running, in that state
deadThe command is gone and the share was not cleaned up
cleanup pendingStopped, but something in the computer could not be removed, or some writes had not arrived

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 machine

Last line in the share’s terminal:

OutputMeaningExit
✓ stopped: everything written in the computer is on this machine, and <path> is gone from the computerDelivery confirmed, mount removed. If rclone exited or a conflict ended the share, ✗ <reason> follows as the last line, exit 10
✗ stopped, but the computer never confirmed it had sent everything here: a write made there may not have reached this machineNothing left in the computer, but unconfirmed, for example mount and backend removed another way1
! stopped by `hoody share stop --force`: what the computer had not sent here was discardedAnother terminal ran stop --force1
✗ 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 needed1
CaseResult
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 shareDiscards 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 exitedNo wait; held writes stay
Mount removed outside hoody shareBackend kept, cleanup pending. Only --force finishes, discarding unsent writes
Computer unreachableA 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 userCannot stop your share
✗ 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
CaseBehaviour
stop on a dead shareStops leftover rclone, removes the mount, waits up to 10 seconds for confirmation. Unconfirmed: backend stays, cleanup pending
stop refuses, exit 1The 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
--forceThe computer deletes the writes; the backend goes once confirmed. Otherwise cleanup pending: run it again. Same for a stop that ended early
LimitDetail
Foreground onlyNo background mode yet
Computer restart during uploadsThose writes stay in the computer, not delivered automatically
One local machine per mountSeveral local machines cannot share into the same mount path in a computer
SymptomCauseFix
I/O error in the computerLocal machine asleep or offline, or command stoppedRunning: 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 yetDelivery takes seconds, or you went offlineWait. If offline, keep sharing until reconnected
Permission denied as userNeeds sudoUse sudo or root
No computer specifiedNone foundPass --computer <id> or -c <id>, or set HOODY_COMPUTER
rclone not found or too oldBelow v1.61.0, or cannot runInstall or update, or use --rclone
an earlier share of "<name>" was not cleaned up: run `hoody share stop <name>`Earlier same-named sharestop, 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` againKit cannot discard writes left by a gone mount or backend; stays cleanup pendingUpdate the kit, rerun
--force always leaves cleanup pendingA damaged or unreadable upload record blocks every share stop on that computerDelete 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 itAnother binding kept the port for five minutes; held writes stay, cleanup pendingstop (--force discards them), share again
conflict: the tunnel came back on another URLReconnected without the original URL; same resultSame

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.

Terminal window
# List the records
hoody files uploads unreadable list -c "$COMPUTER_ID"
# Delete one
hoody files uploads unreadable delete "$RECORD_ID" -c "$COMPUTER_ID"
{"success": true, "message": "Unreadable pending uploads", "data": [{"id": "3f0c9a1e2b7d4c5a8e6f1b2c3d4e5f60", "size": 1048576, "reason": "damaged"}]}