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

hoody share makes a folder on your local machine appear inside a computer. The files stay on your local machine, editable there, and the computer reaches them over the network while the command runs. Programs there read and write the folder like any other directory, and every change lands in it. Use it to run builds, tests or an agent on local files, to hand a computer a dataset without uploading it, or to collect a job’s output on your disk.

Terminal window
hoody -c "$COMPUTER_ID" share ./photos
# In the computer: /hoody/mounts/permanent/photos

The folder is shared while that command runs, so keep the terminal open. Mount Locally is the reverse: it puts the computer’s files on your local machine.

The Hub shows these commands for a computer, ready to copy. Open Files, choose the computer in Browse, open Use from your PC, and choose the option to give that computer a folder from your PC.

  • rclone v1.61.0 or newer on your local machine;
  • the Hoody CLI, signed in to the account that owns the computer;
  • a computer with an up-to-date Hoody Kit;
  • Linux or macOS. Windows is not supported yet, and hoody share is not available over ssh hoody.com.

Share read-only, under a name or into several computers

Section titled “Share read-only, under a name or into several computers”
Terminal window
# Pick the name in the computer: /hoody/mounts/permanent/pics
hoody -c "$COMPUTER_ID" share ./photos --name pics
# Share without allowing any writes
hoody -c "$COMPUTER_ID" share ~/docs --read-only

Everything under the folder is reachable from the computer, so share the project folder, not your home directory. --read-only protects your files from a mistaken write or delete, including one made by an agent.

For several computers, run hoody share once per computer; each run shares the same folder, not a copy.

-c <id> or --computer <id> picks the computer. Without them, hoody share <dir> uses HOODY_COMPUTER or your configured default, and refuses to start when there is none. hoody share stop reads only --computer or -c.

The terminal, exec scripts, the agent, the files API, the SDK (box.files.*) and the web file manager can all use it. Root reaches it directly. In the terminal, exec scripts and the agent, the normal user needs sudo for now.

Inside the computer, it is a directory:

Terminal window
# As root
ls /hoody/mounts/permanent/photos
# As the computer's normal user
sudo ls /hoody/mounts/permanent/photos
sudo cp report.pdf /hoody/mounts/permanent/photos/

In the Hub, open Files, choose the computer in Browse and go to /hoody/mounts/permanent/photos. Deleting a file there deletes it on your local machine.

From outside, use the files API:

Terminal window
# List the shared folder
hoody files get /hoody/mounts/permanent/photos/ -c "$COMPUTER_ID"
# Write a file; it reaches your local machine within a few seconds
echo -n 'written from the computer' | hoody files upload /hoody/mounts/permanent/photos/notes.txt -c "$COMPUTER_ID"

The mount rules apply. A move between the shared folder and the computer’s own files fails with FILE_MOVE_CROSSES_DEVICES: copy the file, then delete the original.

ChangedOther side sees it
In the computerSaved there first, then on your local machine, usually within a few seconds after the file’s last open handle closes
On your local machineIn the computer at once

If a file changes on both sides at the same moment, the version saved last replaces the other; nothing is merged, so avoid editing a file on both sides at once.

What if my local machine sleeps or goes offline?

Section titled “What if my local machine sleeps or goes offline?”

The folder needs your local machine online and hoody share running. Operations that need your local machine can fail with an I/O error (Input/output error in a shell), typically after about 10 seconds for reads and 10 to 20 seconds for writes. Already-open writable files can continue accepting writes into the computer’s cache while offline; a successful write does not confirm delivery to your local machine.

Leave the command running: it reconnects when your local machine is back, on the same URL, with nothing to remount. A failed write is not delivered later, so the program must write it again. A write that succeeded may still be waiting in the computer when your local machine goes offline, so keep the share running and let its stop confirm delivery.

For a long job, keep your local machine awake, or write to the computer’s own storage and copy the result to the share afterwards.

hoody share list shows shares you started on this local machine, on all computers, with status. -o json prints JSON.

Press Ctrl+C once in its terminal, or run this elsewhere:

Terminal window
hoody share stop photos

A stop waits, up to 300 seconds by default, until every write made in the computer reaches your local machine. Once delivery is confirmed, it removes the mount, backend, tunnel and rclone process. Your folder stays as it is, with every write that was delivered.

If the wait ends unconfirmed (timeout, second Ctrl+C, error), the writes and backend stay in the computer, and the mount too unless the stop had already removed it. The tunnel closes and rclone stops, so the share is cleanup pending and the command exits with status 1.

If hoody share was killed or your local machine restarted, the mount and backend stay in the computer and hoody share list shows dead. A stop that ended unconfirmed shows cleanup pending. For both, list prints the cleanup command, hoody share stop <name> --computer <id>.

Without the running command nothing serves the folder, so held writes can never be delivered, and a new share of that name is refused until the cleanup is done. If the computer holds undelivered writes, stop refuses and asks for --force, which discards them. First see what you can find.

hoody share stop reports how many files the computer still holds. Writes held by the active mount may be absent from GET /api/v1/pending-uploads, but writes left after a computer restart can be listed even while the share’s mount still exists. An empty list does not mean nothing is held.

Once the mount is gone, a group can appear. A group in state uploading refuses a download with 409 PENDING_UPLOAD_BUSY until you stop it. Delivering to another registered backend overwrites matching files there.

In the Hub, open Files, choose the computer in Browse, then open Storage. Held groups are listed under Waiting to upload. Show files lists the held files with a Download button for each one. Stop ends an upload, and Discard deletes the held files. The Hub delivers only to the group’s own storage; to deliver to another backend, use the CLI or API below.

These calls act on a listed group; see pending uploads:

Terminal window
# List the groups
hoody files uploads list -c "$COMPUTER_ID"
# Stop a group that is uploading
hoody files uploads stop "$PENDING_ID" -c "$COMPUTER_ID"
# Download one held file
hoody files uploads download "$PENDING_ID" --path notes.txt --out-file notes.txt -c "$COMPUTER_ID"
# Deliver complete files to another backend
hoody files uploads deliver "$PENDING_ID" --backend-id "$BACKEND_ID" -c "$COMPUTER_ID"
  • Clear a damaged record. A damaged or unreadable upload record blocks every share stop on that computer, with or without --force. Deleting it can lose data; see Troubleshooting.
  • Tune a run. --drain-timeout <s>, set when you start the share, changes the stop wait; use it for large writes over a slow link. --rclone <path> picks the rclone binary when the one on your PATH is not the one you want. See options.
  • Check the mount. hoody files mounts list -c "$COMPUTER_ID" shows its status and pending count. If you remove it yourself, a running share reports that, and it is cleanup pending when it stops.
  • Script it. list and stop take -o json. Outside a terminal (a pipe, CI or HOODY_AGENT_MODE=1), messages take the plain form quoted in the reference.
  • Run a share from code. The SDK subpath hoody-sdk/share exports share, stopShare and listShares.

Options, statuses, messages, limits and troubleshooting.