Share a local folder
Section titled “Share a local folder”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.
hoody -c "$COMPUTER_ID" share ./photos# In the computer: /hoody/mounts/permanent/photosThe 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 shareis not available overssh hoody.com.
Share read-only, under a name or into several computers
Section titled “Share read-only, under a name or into several computers”# Pick the name in the computer: /hoody/mounts/permanent/picshoody -c "$COMPUTER_ID" share ./photos --name pics
# Share without allowing any writeshoody -c "$COMPUTER_ID" share ~/docs --read-onlyEverything 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.
Use the folder in the computer
Section titled “Use the folder in the computer”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:
# As rootls /hoody/mounts/permanent/photos
# As the computer's normal usersudo ls /hoody/mounts/permanent/photossudo 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:
# List the shared folderhoody files get /hoody/mounts/permanent/photos/ -c "$COMPUTER_ID"
# Write a file; it reaches your local machine within a few secondsecho -n 'written from the computer' | hoody files upload /hoody/mounts/permanent/photos/notes.txt -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 shared folderconst listing = await box.files.get('hoody/mounts/permanent/photos/');
// Write a file; it reaches your local machine within a few secondsawait box.files.upload('hoody/mounts/permanent/photos/notes.txt', 'written from the computer');# List the shared foldercurl "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/files/hoody/mounts/permanent/photos/"
# Write a file; it reaches your local machine within a few secondscurl -X PUT --data-binary 'written from the computer' \ "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/files/hoody/mounts/permanent/photos/notes.txt"Replace the IDs before clicking. The second link writes notes.txt into your folder.
# List the shared folderhttps://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/files/hoody/mounts/permanent/photos/&method=GET&response=transparent
# Write a filehttps://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/files/hoody/mounts/permanent/photos/notes.txt&method=PUT&data=written%20from%20the%20computer&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
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.
When do changes reach the other side?
Section titled “When do changes reach the other side?”| Changed | Other side sees it |
|---|---|
| In the computer | Saved there first, then on your local machine, usually within a few seconds after the file’s last open handle closes |
| On your local machine | In 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.
List your shares
Section titled “List your shares”hoody share list shows shares you started on this local machine, on all computers, with status. -o json prints JSON.
Stop a share
Section titled “Stop a share”Press Ctrl+C once in its terminal, or run this elsewhere:
hoody share stop photosA 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.
Clean up after a crash
Section titled “Clean up after a crash”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.
Find writes left in the computer
Section titled “Find writes left in the computer”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:
# List the groupshoody files uploads list -c "$COMPUTER_ID"
# Stop a group that is uploadinghoody files uploads stop "$PENDING_ID" -c "$COMPUTER_ID"
# Download one held filehoody files uploads download "$PENDING_ID" --path notes.txt --out-file notes.txt -c "$COMPUTER_ID"
# Deliver complete files to another backendhoody files uploads deliver "$PENDING_ID" --backend-id "$BACKEND_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 groupsconst groups = await box.files.uploads.list();
// Stop a group that is uploadingawait box.files.uploads.stop(PENDING_ID);
// Download one held fileconst file = await box.files.uploads.download(PENDING_ID, { path: 'notes.txt' });
// Deliver complete files to another backendawait box.files.uploads.deliver(PENDING_ID, { backend_id: BACKEND_ID });# List the groupscurl "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads"
# Stop a group that is uploadingcurl -X POST "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/$PENDING_ID/stop"
# Download one held filecurl -o notes.txt "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/$PENDING_ID/file?path=notes.txt"
# Deliver complete files to another backendcurl -X POST -H "Content-Type: application/json" -d '{"backend_id":"'"$BACKEND_ID"'"}' \ "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/$PENDING_ID/deliver"Replace the IDs before clicking. The last link overwrites matching files on that backend. A download writes a file, so it has no link here.
# List the groupshttps://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&method=GET&response=transparent
# Stop a grouphttps://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/PENDING_ID/stop&method=POST&response=transparent
# Deliver complete fileshttps://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/PENDING_ID/deliver&method=POST&json={"backend_id":"BACKEND_ID"}&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
Advanced
Section titled “Advanced”- 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 yourPATHis 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 iscleanup pendingwhen it stops. - Script it.
listandstoptake-o json. Outside a terminal (a pipe, CI orHOODY_AGENT_MODE=1), messages take the plain form quoted in the reference. - Run a share from code. The SDK subpath
hoody-sdk/shareexportsshare,stopShareandlistShares.
Reference
Section titled “Reference”Options, statuses, messages, limits and troubleshooting.
What’s Next
Section titled “What’s Next”- Computer Storage: the computer filesystem and
/hoody/mounts - Cloud Storage: mount remote storage providers
- SQLite Driver: where to keep databases instead
- Tunnel: how your local machine reaches the computer
- Shared Storage: share a directory between computers