# Mount

> Browse the whole box in Finder as a live network drive; nothing is copied and it uses no disk space on your Mac.

URL: https://prized.dev/docs/mount

> macOS only. On Linux and Windows the command refuses and points at [sync](https://prized.dev/docs/sync) and `prized ssh` instead.

## Usage [#usage]

```bash
prized mount                                # the configured box, in the background
prized mount mango                          # any box on your account
prized mount --dir /var/log --read-only     # one directory, read-only
prized unmount                              # stop the mount and detach the volume
```

`prized mount` wakes the box, mounts its home directory at `~/Prized/boxes/<box>` (in Finder under Locations as `<box>.localhost`), opens it in Finder, and returns; the mount outlives the terminal. Run it again for a mounted box and it opens the folder. `prized unmount [BOX]`, or ejecting the volume, stops it.

| Flag                 | What it does                                                 |
| -------------------- | ------------------------------------------------------------ |
| `--dir`              | Export this box directory instead of the home directory.     |
| `--at`               | Mount somewhere other than `~/Prized/boxes/<box>`.           |
| `--read-only`        | Serve a read-only view.                                      |
| `--no-open`          | Do not open the folder in Finder.                            |
| `--foreground`, `-f` | Serve from this terminal until Ctrl-C.                       |
| `--mount-opt`        | Extra NFS mount options, comma-separated, appended verbatim. |

One mount per box. A background mount logs to `~/Library/Logs/prized/mount-<box>.log`; `prized mount` and `prized unmount` take `--json`.

## When the box sleeps or the connection drops [#when-the-box-sleeps-or-the-connection-drops]

The volume survives a pause, your Mac sleeping, or a dropped connection: the next access waits for the box to wake and reconnect (Finder may spin for a few seconds), and a copy in progress resumes rather than failing. Ten minutes without a connection unmounts it; `prized mount` brings it back.

## Mount or sync? [#mount-or-sync]

| You want                                              | Use                |
| ----------------------------------------------------- | ------------------ |
| a working copy on your Mac, fast for builds and git   | [sync](https://prized.dev/docs/sync) |
| to browse, preview, edit, or grab anything on the box | mount              |

Each uncached operation on a mount is a network round trip: browsing, Quick Look, editing a file, and copying either way feel fine; builds or `git status` on a large repo do not.

## How it works [#how-it-works]

The stock macOS NFS client talks to a server the CLI runs on 127.0.0.1, which reaches the box over SFTP through the `prized ssh` tunnel. Nothing kernel-side is installed, no sudo is needed, and your Mac holds file bytes only in memory.

> [!WARNING]
> That local server does not authenticate its clients: on a Mac shared with other user accounts, treat a mount as readable by them. Export a narrower `--dir`, add `--read-only`, and `prized unmount` when you are done.

## Troubleshooting [#troubleshooting]

| Symptom                                                                             | Fix                                                                                                                                   |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Startup times out                                                                   | The box stopped answering before the volume was ready: `prized doctor`, then retry. With `--foreground`, Ctrl-C also cancels startup. |
| "already mounted at ... read-only, not writable" (or a different `--dir` or `--at`) | The mounted volume does not match your options: `prized unmount <box>`, then mount again.                                             |
| "mountpoint is not empty"                                                           | A mount left by a previous run: `umount ~/Prized/boxes/<box>` and retry.                                                              |
| "Operation not permitted" listing the folder in a terminal                          | Give your terminal Full Disk Access (System Settings > Privacy and Security), or use Finder.                                          |
| "secure sftp helper failed (update prized-agent on the box)"                        | The box's agent predates mount; update it and retry.                                                                                  |
| The folder hangs on a box that no longer exists                                     | A deleted or stopped box cannot be woken; `prized unmount <box>` detaches the volume.                                                 |