# Mount

> See the whole box in Finder as a network drive, served live over the tunnel. Nothing is copied; the mount uses no disk space on your Mac.

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

> Mount is macOS-only: it is built on the stock macOS NFS client, so 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 if it sleeps, mounts its home directory at `~/Prized/boxes/<box>`, opens it in Finder, and returns. The volume is served by a background process, so it outlives the terminal; it also appears under Locations in Finder as `<box>.localhost`. Run `prized mount` again for a mounted box and it just opens the folder. `prized unmount [BOX]` stops the mount, as does ejecting the volume in Finder.

| 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`          | Skip opening the mounted folder in Finder.                             |
| `--foreground`, `-f` | Serve from this terminal until Ctrl-C instead of a background process. |
| `--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`; `--json` works with `prized mount` and `prized unmount`.

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

The volume stays mounted. If the box pauses, your Mac sleeps, or the connection drops, the next thing that touches the folder waits while the box is woken and reconnected, then continues; a copy in progress resumes rather than failing. Finder may show a spinner for a few seconds while a paused box wakes. Only a connection that stays down for ten minutes unmounts the volume; `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  |
| to browse, preview, edit, or grab anything on the box | mount |

A [synced project](https://prized.dev/docs/sync) is a mirrored folder pair: local disk, one project, fast. A mount is a live window over the whole box with a network round trip per uncached operation: browsing, Quick Look, editing a file, and copying files in either direction feel fine; builds or `git status` on a large repo do not.

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

The stock macOS NFS client points at a server the CLI runs on 127.0.0.1, whose backend is an SFTP session to the box over the same tunnel `prized ssh` uses. Nothing kernel-side is installed, no sudo is needed, and your Mac holds file bytes only in memory.

> That local server does not authenticate its clients, so on a Mac you share 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]

* **"already mounted at ... read-only, not writable"** (or a different `--dir` or `--at`): the volume that is up does not match what you asked for; `prized unmount <box>`, then mount again with the options you want.
* **"mountpoint is not empty"**: a mount left by a previous run; `umount ~/Prized/boxes/<box>` and try again.
* **"Operation not permitted" listing the folder in a terminal**: grant 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 the mount helper; update it and try again.
* **The folder hangs on a box that no longer exists**: a deleted or stopped box cannot be woken; `prized unmount <box>` detaches the volume.