# Share a local folder reference
**Page:** foundation/storage/share-local-folder/reference
[Download Raw Markdown](./foundation/storage/share-local-folder/reference.md)
---
# Share a local folder reference
Lookup for `hoody share`; the [guide](/foundation/storage/share-local-folder/) covers everyday use.
## Commands and options
```bash
hoody share
[--name ] [--read-only] [--computer ] [--rclone ] [--drain-timeout ]
hoody share list [-o json]
hoody share stop [--computer ] [--force] [-o json]
```
| Option | Meaning |
|---|---|
| `--name ` | Folder's name in the computer. Default: base name of the resolved folder path; if `` 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 ` | Without it, a share uses global `-c `, then `HOODY_COMPUTER` or your configured default, or refuses to start. `stop` reads only this or `-c `, so a default never hides a same-named share elsewhere |
| `--rclone ` | rclone binary to run. Default: `rclone` on your `PATH` |
| `--drain-timeout ` | `hoody share ` 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
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.
```bash
brew install rclone # macOS
apt install rclone # Linux; or: dnf install rclone
```
```text
the files kit of computer 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.
```
## Folder and name rules
| Case | Rule |
|---|---|
| `` | 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` |
```text
share name "" is not allowed: use 1-64 characters from A-Z a-z 0-9 . _ -, not "." or "..", and not starting with "-". Example: --name
"" is already shared to computer 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 `✗ `.
## 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.
```text
✓ is shared
In the computer:
Through:
Press Ctrl+C to stop, or run `hoody share stop --computer `.
```
```text
Sharing into computer …
is shared
in the computer
through
ctrl-c stops, or run hoody share stop --computer
```
## 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
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
rclone serves WebDAV on your local machine's loopback address. A [hoody-tunnel](/kit/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](/foundation/storage/cloud/) credential; you never need it. The address stays open until you stop the share.
## `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
A stop starts from `Ctrl+C`, `hoody share stop ` (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:
```text
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:
| Output | Meaning | Exit |
|---|---|---|
| `✓ stopped: everything written in the computer is on this machine, and is gone from the computer` | Delivery confirmed, mount removed. If rclone exited or a conflict ended the share, `✗ ` 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: ` | 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
| Case | Result |
|---|---|
| `hoody share stop`, clean | `✓ stopped (computer )` (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 | `"" 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 ` 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
```text
✗ 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](/foundation/storage/share-local-folder/#find-writes-left-in-the-computer) 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
| 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
| 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 ` or `-c `, 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 "" was not cleaned up: run `hoody share stop ` `` | Earlier same-named share | `stop`, adding `--force` if it reports unsent writes |
| `` the files kit of computer is too old to discard what a removed mount or backend left; update it, then run `hoody share stop --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](/kit/files/#unreadable-records) |
| `conflict: computer 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.
```bash
# List the records
hoody files uploads unreadable list -c "$COMPUTER_ID"
# Delete one
hoody files uploads unreadable delete "$RECORD_ID" -c "$COMPUTER_ID"
```
```typescript
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 records
const records = await box.files.uploads.listUnreadable();
// Delete one
await box.files.uploads.deleteUnreadable(RECORD_ID);
```
```bash
# List the records
curl "https://$PROJECT_ID-$COMPUTER_ID-files-1.$SERVER.computers.hoody.com/api/v1/pending-uploads/unreadable"
# Delete one
curl -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.
```json
{"success": true, "message": "Unreadable pending uploads", "data": [{"id": "3f0c9a1e2b7d4c5a8e6f1b2c3d4e5f60", "size": 1048576, "reason": "damaged"}]}
```