# Overview
> Prized gives you a dedicated Linux box in the cloud. Your files appear in a folder on your Mac, box ports appear on your localhost, and terminal sessions survive closing the laptop.
URL: https://prized.dev/docs
## How it works [#how-it-works]
You edit and run everything on the box over SSH. Three things connect it to your laptop: files sync both ways with a folder on your Mac, .git included; a dev server you start on the box appears on your laptop's localhost within seconds; and terminal sessions run in tmux, so they survive a closed lid.
## The pieces [#the-pieces]
| Piece | What it is |
| -------------- | ------------------------------------------------------------------------------------- |
| `prized` | The CLI on your laptop. |
| `prizedd` | A background daemon on your Mac. Runs the sync and mirrors box ports onto localhost. |
| `prized-agent` | A service on the box. Discovers listening ports, reports vitals, lists tmux sessions. |
| Dashboard | prized.dev. Create boxes, watch their state, manage billing. |
## What's on the box [#whats-on-the-box]
Ubuntu, preloaded with Docker (compose and buildx), git, tmux, mosh, ripgrep, jq, and the GitHub CLI. You have root, so apt and any toolchain installer work normally. Claude Code and Codex are preinstalled and Cursor's CLI installs on demand; `prized setup` hands your own sign-ins over from your Mac, so the box's agents are yours without retyping an OAuth flow. See [Credentials](/docs/credentials).
## All pages [#all-pages]
From signup to a synced project in about five minutes.
Two-way file sync between the box and your laptop, .git included.
Servers on the box appear on your laptop's localhost.
Terminal sessions that survive closing the laptop.
Claude Code, Codex, or Cursor on the box, signed in by handoff, working
overnight; review in the morning.
Create, pause, resize, snapshot, and delete boxes.
Git, cloud, and model credentials live on your box.
Every prized command, with flags and examples.
Monthly plans, hourly rates, and the balance your plan refills.
prized doctor and fixes for the common failures.
---
# Quickstart
> Four steps from signup to a box with your project on it and your coding agent signed in. You need a Mac.
URL: https://prized.dev/docs/quickstart
## 1. Sign up and create a box [#1-sign-up-and-create-a-box]
Go to [prized.dev](/sign-in) and sign up. You can walk through the tour and look around the dashboard before paying for anything; what needs a plan is running a box.
Choosing a plan is what starts your first box, so there is no separate size to pick: each plan is priced to run one size around the clock, and the $100 plan gets you a Small. Your first cycle's credit lands before you are back from Stripe and the box boots while you install the CLI, which takes about the same minute. After that, boxes bill by the hour from that credit, so a shape the balance could not keep running for four hours cannot be created (unless you switch on overage, which bills the extra with your next invoice instead); see [Billing](/docs/billing) for the plans and rates.
## 2. Install the CLI [#2-install-the-cli]
```bash
curl -fsSL https://prized.dev/install.sh | sh
```
This installs `prized`, its background daemon, and a Prized-managed copy of Mutagen, which powers sync; there is nothing else to install. Re-running the installer upgrades in place, and `prized update` does the same from inside the CLI. If the Mutagen download fails because you were offline, `prized setup` fetches it later. Once you are signed in the CLI reports command usage (never arguments or file contents) to help us fix bugs; [it is easy to turn off](/docs/cli#usage-telemetry).
## 3. Log in [#3-log-in]
```bash
prized login
```
Your browser opens the dashboard, where you mint a CLI token. Paste it back into the terminal. The CLI stores it in `~/.config/prized` and sets up your SSH identity. Tip: the install command shown during onboarding carries a single-use link that does this step for you.
## 4. Set up [#4-set-up]
```bash
prized setup
```
One command for the rest, safe to re-run at any time. `setup` finds the box on your account, writes the config, installs the SSH stanza, starts the background daemon, and runs a health check; re-run it later and it converges whatever is missing without clobbering anything. Then it offers the optional parts, asking before the first two:
* **Project.** Name one (`prized setup myproject`) and it creates `~/code/myproject` on the box, mirrored to `~/Prized/myproject` on your Mac, both ways, .git included. Pass a path (`prized setup ~/src/myproject`) and setup offers three modes for it: synced in place (the folder itself is the live Mac side, box wins conflicts), `--copy` (a copy under `~/Prized`, original untouched), or `--clone` (a git clone on the box, no live mirror; right for a checkout other people or agents also edit). See [Sync](/docs/sync).
* **Agents.** Pick from Claude Code, Codex, Cursor, and the ChatGPT app, and setup hands each one to the box: its sign-in and MCP servers travel over the SSH tunnel, so the box is signed in without retyping any OAuth flow. It lists exactly what would be copied and asks per agent; see [Credentials](/docs/credentials).
* **Session.** With exactly one runnable agent picked, setup starts it in a detached tmux session on the box and prints the reattach command, no extra question; pass `--no-start` to skip this. That session keeps running with your laptop closed.
Connect any time with `prized ssh`, which lands you in a persistent tmux session; a dev server started there appears on your laptop's localhost within seconds.
> Check everything at once with `prized status`: box vitals, sync state, mirrored ports, daemon health.
## Or let an agent do it [#or-let-an-agent-do-it]
Steps 2 through 4 are one paste into your coding agent. Onboarding composes the prompt for you: its connect step asks setup's questions in the browser (your agent, then the project and how it reaches the box) and bakes the answers in, GitHub handoff included, ready for Claude Code, Codex, Cursor, or Codex in the ChatGPT app. The generic prompt, for a later machine, is on [Agent setup](/docs/agent-setup).
---
# Agent setup
> Paste one prompt into Claude Code or Codex on your Mac; the agent installs the CLI, runs prized setup, and asks before putting your project or your credentials on the box.
URL: https://prized.dev/docs/agent-setup
## One prompt [#one-prompt]
Onboarding builds this prompt for you: after your first box boots, the connect step asks setup's questions in the browser (your agent, then the project and how it reaches the box) and composes the prompt with those answers already carried as flags, so the agent has nothing to re-ask. The composed prompt includes the GitHub handoff (`--gh`) by default; the prompt spells it out, and you can delete that flag before pasting if you do not want gh on the box. Copy it there and you are done.
The version below is the generic template for every other time: a later machine, a fresh start, or when you would rather the agent relay your choices itself. Open your agent on the Mac, in the project you want on the box, and paste this. It covers steps 2 through 4 of the [Quickstart](/docs/quickstart); you still create the box in the [dashboard](/dashboard) if you have not already.
```text
Set up Prized on this Mac and, if I confirm each part, put this project
and my coding agents on my box. Prized is a cloud dev box that syncs
folders with this machine; the docs live at https://prized.dev/docs
(plain-text mirror at /llms-full.txt).
Rules: copy, never move or delete; never print credentials or read
~/.config/prized; ask me before installing software, before transferring
any credential, and before doing anything that could cost money.
Non-interactive prized commands accept --json and print exactly one JSON
object with an "ok" field; error codes and exit codes are stable and
listed at https://prized.dev/docs/cli.
1. Install: if `prized version` fails, ask me, then run
`curl -fsSL https://prized.dev/install.sh | sh` and re-check.
2. Sign in: if prized commands fail with code AUTH or a "prized login"
hint, stop and ask me to run `prized login` in another terminal (it
needs my browser). I can instead paste a CLI token from the dashboard
for you to use as `prized login --token `.
3. Everything else is one command, safe to re-run:
`prized setup --json --non-interactive`. It never prompts; each
consent-gated step runs only when its grant flag is present and is
reported as skipped otherwise. Ask me before adding each flag, and
only pass the ones I say yes to:
- `--project `: sync this folder with the box in place; the
folder itself becomes the live side and the box wins conflicts.
Ask me first. Two alternatives are their own distinct grants, so
relay my choice exactly: `--copy` syncs a copy under ~/Prized and
leaves the folder alone; `--clone` clones the repo onto the box
over git with no live mirror, the right choice for a repo I
actively work in elsewhere. Say which one I picked in your
report; if I say no to all of them, run setup without --project.
- `--agent claude|codex|cursor|chatgpt` (repeatable): hand that
agent's sign-in and MCP config to the box. Ask me per agent.
- `--install-cursor`: run Cursor's installer on the box. Its own yes.
- `--gh`: copy my GitHub CLI token and git identity. Its own yes.
If setup fails with exit 5 naming multiple candidate boxes, ask me
which one and re-run with `--box `; if it finds no box on the
account, ask me to create one in the dashboard. Read steps[] in the
JSON: "skipped" entries name what was declined or not granted,
"failed" entries carry the hint.
4. Claude Code sign-in is my step, not yours: it needs a browser
(`claude setup-token`), so a non-interactive run reports claude auth
as manual. If I picked claude, ask me to run
`prized setup --agent claude` myself in another terminal; the token
goes from my Mac to the box directly and you never see it. Then
continue.
5. Verify: `prized status --json` reports ok; if we set up the project
as a sync (not `--clone`; a clone has no sync session), also that
`prized sync flush ` completes. Check
`prized agents ls --json` shows each chosen agent installed and
signed in on the box.
6. Report: the box name, the project path on both sides (or the clone
path on the box, or that I chose to keep this repo local), which
project mode I granted, each agent's handoff outcome, and the
reattach command for any session setup started.
```
## What it asks you [#what-it-asks-you]
Sign-in: `prized login` opens your browser, so the agent stops and asks. Run it yourself in another terminal, or mint a CLI token in the dashboard and hand it over for `prized login --token`.
The transfer: the agent confirms before it passes `--project`, so pasting the prompt in the wrong window never ships a project you did not mean to sync. The grant means sync in place: the named folder becomes the live Mac side of the pair, no copy, and the box wins conflicts in it from then on. The two alternatives are distinct grants the agent relays only when you pick them: `--copy` syncs a copy under `~/Prized` and leaves your folder alone, and `--clone` puts a git clone of the repo on the box with no live mirror, which is the safe choice for a repo you actively work in elsewhere. Say no to all three and it still leaves you a signed-in CLI and a healthy box; add projects later with `prized setup ` or `prized sync add`. The modes are compared in [Sync](/docs/sync#add-a-project).
The credentials: in `--non-interactive` mode, `prized setup` skips every consent-gated step whose grant is missing, so the agent has to relay your yes as a flag: `--agent ` per agent, `--install-cursor` for the on-box installer, `--gh` for your GitHub token. One grant is not a flag: if you have picked agents on this Mac before, that choice is saved in `[agents].preferred` and a later run hands those agents off without `--agent`. That is the naming you already did, and it is why a re-run converges instead of asking again; pass `--no-agents` for a run that must depend on nothing but its own flags (the prompt the dashboard composes does exactly that when you pick "my agent is not listed"). Nothing else is copied that you did not name, the transfer runs over the SSH tunnel straight to the box, and the agent never handles a credential value; see [Credentials](/docs/credentials).
Claude Code is the one sign-in the agent cannot do for you: `claude setup-token` needs your browser, so you run `prized setup --agent claude` in your own terminal when it asks.
Everything else is safe to leave to the agent. Every prized command in the prompt is safe to re-run, and a skipped or failed step is named in the JSON report rather than half-applied. The folder-pair model it sets up is described in [Sync](/docs/sync); for running agents on the box afterwards, see [Agents](/docs/agents).
---
# Sync
> A synced project is one folder pair, ~/code/ on the box mirrored into a folder on your Mac. Edits land on the other side in under a second, both directions, .git included.
URL: https://prized.dev/docs/sync
## The model [#the-model]
| Side | Path |
| -------- | ---------------------------- |
| box | `~/code/` |
| your Mac | `~/Prized/` by default |
`prized sync add ` wires the pair and keeps it mirrored both ways. `~/Prized` is the default home for projects without a local override: pass `--local` to sync a folder of your own in place, or set `local_root` under `[sync]` in the config to move the default parent for everything. (An install from before the rename keeps `~/Doppel` as that default parent; see [doppel is now Prized](/docs/rename).)
Sync keeps a real local copy, which is what makes tools that scan a whole repo fast. To look through the box without copying anything, use [mount](/docs/mount) instead.
## Add a project [#add-a-project]
Pick the line that matches where the code is today.
**Starting fresh.** Nothing exists yet on either side:
```bash
prized sync add myproject --create
```
`--create` makes `~/code/myproject` on the box; the empty pair fills up as you (or an agent) work.
**The code is on the box.** Mirror it down:
```bash
prized sync add myproject
```
The first sync copies `~/code/myproject` into `~/Prized/myproject`. Pass a path to sync a folder outside `~/code`: `prized sync add ~/work/api` derives the name `api`.
**The code is on your Mac.** Point setup at it:
```bash
prized setup ~/src/myproject
```
Setup offers three ways to get an existing folder onto the box; pick by how the folder is used.
**Sync in place** is the default: your folder becomes the live Mac side of the pair, no copy. The first sync uploads it to `~/code/myproject` on the box, and edits mirror both ways from then on; the project name is the folder's basename. Setup asks before wiring it, and the confirm states the conflict rule below, because it now applies to that folder: when the same file changes on both sides at once, the box side wins. Right for a project one person edits. Doing it by hand is one command:
```bash
prized sync add --local ~/src/myproject --create
```
The path must already exist; `--create` refers to the box side, and `--name` overrides the derived name.
**Copy** leaves the folder untouched and syncs a copy instead:
```bash
prized setup ~/src/myproject --copy
```
That copies the folder into `~/Prized/myproject` (a copy, never a move) and syncs the copy; the original is out of the loop from then on. Keep it until you have used the synced copy for a while, then retire it; two live copies of a repo on one Mac invites editing the wrong one. Running the same command again is safe and copies nothing a second time: it reports that `~/Prized/myproject` is already the synced side and moves on.
**Clone on the box** skips the mirror entirely and lets git be the transport:
```bash
prized setup ~/src/myproject --clone
```
Setup reads the folder's `origin` remote and clones it to `~/code/myproject` on the box: `gh repo clone` for github.com origins, riding your GitHub sign-in, plain `git clone` otherwise. It then checks out your current branch when it exists on origin. There is no live mirror and no sync session; work moves by push and pull, so nothing on your Mac can race an agent on the box, and nothing on the box can overwrite an edit on your Mac. That makes clone the right mode for a checkout that is not one person's to mirror: other people or several concurrent agents edit it, worktrees live inside it, uncommitted work is in flight. A live mirror of a checkout like that can lose concurrent work, and setup says so: when it detects linked worktrees in the folder, its recommendation flips from in place to clone. A clone is not a sync project, so it does not appear in `prized sync ls`; it is just a git checkout on the box.
If both sides already have content, `add` refuses until you pass `--merge`, which accepts the conflict rule below for every same-path difference in the initial merge.
A folder cannot be added inside another synced folder, or the other way round: two sessions would sync the same bytes and fight over them. That refusal comes before anything is created, so a refused add leaves no new folders on either side.
> Each project's Mac folder must stand alone: `add` refuses a folder that is the same as, inside, or around another synced project's folder, because two sessions over the same files fight each other.
Build artifacts like `node_modules`, `dist`, and `target` are ignored by default. Adjust per project with `--ignore` and `--unignore`.
## Conflicts: the box wins [#conflicts-the-box-wins]
Sync runs in two-way-resolved mode and the box wins every conflict: agents on the box write at high rate, so if the same file changes on both sides at once, the Mac edit yields. This matters most for a folder synced in place: the folder you have always edited is now the yielding side of the pair, so an edit that races an agent on the box loses. Prefer the other side per project with `--prefer mac`, or use `--mode two-way-safe` to surface conflicts instead of resolving them.
> Files larger than 256 MB are skipped; the rest of the project syncs normally.
## Git over sync [#git-over-sync]
The box is the write side of git: commit, rebase, and push from a shell there. Reading from your Mac is always safe, so history, diffs, and blame in `~/Prized` are fine. Committing from the Mac works too, but only while the box side is quiet: two commits landing at once can lose the Mac one.
## Offline [#offline]
Agents, builds, and servers keep running when your laptop goes offline. Sync catches up when you reconnect, and mirrored ports come back with it. To edit offline in a project an agent is also writing to, pause the project first, or the box's versions win on reconnect.
## Everyday commands [#everyday-commands]
| Command | What it does |
| ------------------------------ | -------------------------------------------------------------------------- |
| `prized sync ls` | List projects with their state and conflicts. |
| `prized sync flush myproject` | Force a full sync cycle and wait for it. Useful before switching machines. |
| `prized sync pause myproject` | Stop syncing until you resume. `--all` works too. |
| `prized sync resume myproject` | Resume a paused project. |
| `prized sync repair myproject` | Recover a halted session with a safe re-scan. No deletions propagate. |
## Remove a project [#remove-a-project]
```bash
prized sync rm myproject
```
By default this only stops the sync; files stay on both sides. Add `--delete-local` to move the Mac folder to the Trash, or `--delete-box` to move the box folder aside. Both are moves, never `rm -rf`, and both name the exact path in the confirm.
Which folder `--delete-local` means depends on the mode you added the project with. For a mirror under `~/Prized` it is Prized's own copy of what is also on the box. For a project synced in place it is your own checkout, the one you pointed setup at, so that prompt asks you to type `delete-local` to confirm, the way `--delete-box` asks you to type `delete-box`. A clone has no Mac side at all, so the flag does not apply to it.
Sync commands only ever touch the box in the config you point them at. If you have several boxes and run one against a second box's config, a project of the same name on another box is left alone and named in the error rather than removed, paused, or listed as yours. The background daemon draws the same line: another box's projects stay out of `prized sync ls` and `prized status`, and it never pauses, resumes, or rebuilds them. Projects you synced before updating are unmarked and stay with the daemon's box, so nothing disappears from the list when you update.
> If a session halts after a folder was deleted at its root, resume is refused, since it would propagate the mass delete. Run `prized sync repair myproject` instead.
## Under the hood [#under-the-hood]
Sync runs on Mutagen, and Prized installs and manages its own pinned copy; there is nothing to set up. If the copy is ever missing, `prized doctor --fix` fetches it.
> Installed Mutagen yourself for an early release? Prized now uses its own copy and ignores the one on your PATH. If projects look gone after updating, run `prized sync repair myproject` once per project; the Homebrew mutagen can be uninstalled.
---
# Mount
> See the whole box in Finder as a local volume, 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 experimental. The command works end to end, but a dropped
> connection unmounts rather than reconnecting, and details may change.
## The model [#the-model]
```bash
prized mount
```
wakes the box if it sleeps, mounts its home directory at
`~/Prized/boxes/`, and opens the folder in Finder. Everything you see is
served live from the box: no sync, no local copy, no disk used. Press Ctrl-C
in the terminal to unmount.
It mounts as a real volume, so it also appears in the Finder sidebar under
Locations, named `.localhost`. Ejecting it there unmounts and exits the
command, the same as Ctrl-C.
Mount and [sync](/docs/sync) answer different questions:
| You want | Use |
| --------------------------------------------------- | ----- |
| a working copy on your Mac, fast for builds and git | sync |
| to browse, preview, or grab anything on the box | mount |
A synced project is a mirrored folder pair that costs local disk and covers
one project. A mount is a live window over the whole box that costs nothing
locally, at the price of a network round trip per uncached operation. Browsing
folders, Quick Look, editing a file, and dragging files out all feel fine;
running builds or `git status` on a large repo against a mount does not. Keep
working sets in sync, and reach for mount when you need to see everything.
## Usage [#usage]
```bash
prized mount # the configured box
prized mount mango # any box on your account
prized mount --dir /var/log --read-only
```
| Flag | What it does |
| ------------- | ------------------------------------------------------------ |
| `--dir` | Export this box directory instead of the home directory. |
| `--at` | Mount somewhere other than `~/Prized/boxes/`. |
| `--read-only` | Serve a read-only view. |
| `--no-open` | Skip opening the mounted folder in Finder. |
| `--mount-opt` | Extra NFS mount options, comma-separated, appended verbatim. |
The command stays in the foreground while the volume is mounted. Ctrl-C
unmounts and exits; closing the terminal does the same.
## How it works [#how-it-works]
The mount is the stock macOS NFS client pointed 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 and no sudo is needed.
File bytes flow straight between Finder and the box; your Mac only ever holds
them in memory.
> If the box suspends or the connection drops, the volume is unmounted so
> Finder never hangs on a dead mount. Run `prized mount` again to remount.
## Troubleshooting [#troubleshooting]
**"mountpoint is not empty".** Something is already at that path, usually a
mount left by a previous run. Unmount it and try again:
```bash
umount ~/Prized/boxes/
```
**"Operation not permitted" listing the folder in a terminal.** macOS gates
access to network volumes per application. Finder has that access; your
terminal may not. Grant it Full Disk Access in System Settings under Privacy
and Security, or use Finder for that folder.
---
# Ports
> Start a server on the box and open it on your laptop as localhost, with no flags or config. Mirroring is on by default and takes a few seconds.
URL: https://prized.dev/docs/ports
## How it works [#how-it-works]
The agent on the box watches for listening TCP ports. When one appears, the daemon on your Mac opens the same port on 127.0.0.1 and tunnels it to the box. Servers that bind only to the box's loopback, like Vite and most dev servers, are relayed by the agent. Websockets are supported.
```bash title="you@box ~/code/myproject"
npm run dev
# ready on http://localhost:3000
# two seconds later, localhost:3000 works on your Mac
```
## Inspect and toggle [#inspect-and-toggle]
`prized ports ls` lists every box listener with its process and mirror state. `prized ports toggle 3000` flips a port off or back on, and the preference persists across restarts.
Both commands describe the box in the config you point them at. If that is not the box the daemon is serving (`--config` or `PRIZED_CONFIG` for a second box), `ports ls` still lists that box's listeners but shows the mirror state as `unknown (daemon serves )`, and `toggle` is refused, since the mirrors that exist belong to the other box. Make the box you want mirrored the default with `prized init --force`, or forward a single port by hand with `prized proxy`.
## Limits [#limits]
Mirroring is TCP only; UDP is not forwarded. Auto-mirroring covers ports 3000 through 9999, and the range and the per-port allow and never lists are configurable in the config's `[ports]` section. Ports below 1024, port 22, and the agent's own port 7377 are never mirrored, and 5900 is excluded by default; anything else outside the range needs an allow-list entry or a manual `prized proxy`.
If something on your Mac already listens on a port, the local process wins and the mirror waits. Every mirrored request also crosses the network, so an app that makes hundreds of database round trips per page should run next to its database on the box, with only the app port mirrored.
## Forward a port by hand [#forward-a-port-by-hand]
Automatic mirroring covers your configured box. For a one-off forward, or another box, use `prized proxy box-3fa9 5432`, which forwards `127.0.0.1:5432` to that box until you press Ctrl-C. An interactive `prized ssh` session to a non-default box forwards that box's ports for the life of the session.
---
# Sessions
> Your shell runs on the box. A network drop or a closed lid ends the connection but not the session; reconnect and you are where you left off, running processes included.
URL: https://prized.dev/docs/sessions
## Connect [#connect]
```bash
prized ssh
```
This lands in a persistent tmux session named `main`. Run it again from anywhere and you attach to the same session; a suspended box wakes on connect. Use named sessions to keep workstreams apart: `prized ssh -s agents`. List them with `prized ssh --ls`, close one with `prized ssh --kill agents`. Session names use letters, digits, hyphens, and underscores; tmux does not allow dots.
For a plain shell without tmux, pass `--raw`. To run a one-off command and get its exit code back: `prized ssh -- make test`.
A session does not need you attached at birth either: `prized agents run codex` starts a coding agent in a detached session on the box and prints the reattach command, so the session exists without your laptop ever holding a connection to it. See [Agents](/docs/agents).
> Sessions survive disconnects and closed lids, but a pause depends on the box size: Extra Small and Small boxes hibernate with processes intact, Medium and larger boxes stop cleanly and processes restart. If you switched on [auto-pause](/docs/boxes#auto-pause) for the box, a session producing output or burning CPU keeps it awake; a session sitting at a prompt does not. See [Boxes](/docs/boxes#pause-and-resume).
## Mosh for flaky networks [#mosh-for-flaky-networks]
```bash
brew install mosh
prized mosh
```
`mosh` attaches to the same tmux session over UDP. Keystrokes echo instantly, and the connection survives IP changes and laptop sleep. The box needs no public port; the traffic uses the same tunnel as SSH.
## Drag files in [#drag-files-in]
Drag a file from Finder onto your session window and it lands on the box: the CLI uploads it over the tunnel into a fresh folder under `~/.prized/drops/` there and pastes the box path instead of the Mac one. Drop a screenshot into Claude Code's prompt this way and the agent can open it, because the path it received exists on the box.
* Works in `prized ssh` and `prized mosh` sessions, with one file or several at once, up to 512 MB per drop.
* Only a paste that is nothing but local file paths rewrites — that is what a drop looks like from every terminal (Ghostty included), and what pasting a copied Mac path looks like too. A path you type, a path inside other text, or a box path goes through untouched.
* If an upload fails, the original Mac path is pasted exactly as before, and the tmux status line says what went wrong. Bigger uploads announce themselves there too.
* A drop appears on the box all at once or not at all — a failed upload never leaves half of one. Drops older than 7 days are cleaned out of `~/.prized/drops/` automatically.
* Turn it off for one session with `--no-drop-upload`, or for good with `drop_upload = false` under `[ssh]` in the config.
## Editors and other tools [#editors-and-other-tools]
Two ways to edit. Use your local editor on the synced folder, where saves (to `~/Prized/myproject` by default) land on the box in under a second. Or work directly on the box: `prized setup` installs an SSH config stanza, so anything that speaks SSH reaches it by hostname: `ssh box-3fa9`, Cursor and VS Code Remote-SSH, scp, rsync, git remotes. Remote-SSH sees the whole box, including folders you never synced. The ChatGPT desktop app rides the same stanza to run Codex on the box; see [Codex remote](/docs/codex).
---
# Agents
> Start a coding agent, close the laptop, and let it work. An agent is an ordinary process on a machine you already pay for, so nothing it does is metered.
URL: https://prized.dev/docs/agents
## Start an agent [#start-an-agent]
```bash
prized agents run claude
```
This starts Claude Code in a detached tmux session named `claude` on the box, working directory your synced project, and prints the reattach command. The session is created detached on the box, so your laptop's state never mattered to begin with: close the lid and the agent keeps working. Reattach with `prized ssh -s claude`, or pass `--attach` to land in the session as it starts. If the session already exists, `run` reports it as already running instead of starting a duplicate.
`--dir` picks the working directory (it defaults to your only synced project when there is exactly one); anything after `--` is passed to the agent as arguments. A project [cloned on the box](/docs/sync#add-a-project) is not a synced project, so it never feeds that default: pass `--dir ~/code/` yourself.
> A detached session survives a closed laptop, but not every pause: Extra Small and Small boxes hibernate with processes intact, while Medium and larger boxes stop cleanly on pause, so processes restart. A working agent also holds off [auto-pause](/docs/boxes#auto-pause) if you enabled it, since its output and CPU count as activity; once the agent finishes, the idle countdown starts. See [Boxes](/docs/boxes#pause-and-resume).
## The four agents [#the-four-agents]
| Agent | On the box | Runs on the box |
| ----------------------- | ----------------------------------------- | --------------- |
| Claude Code (`claude`) | Preinstalled. | Yes. |
| Codex CLI (`codex`) | Preinstalled. | Yes. |
| Cursor (`cursor`) | Installed on demand (`--install-cursor`). | Yes. |
| ChatGPT app (`chatgpt`) | Drives `codex` over SSH from your Mac. | No; see below. |
`chatgpt` is a connection, not a process on the box: the ChatGPT desktop app runs Codex against the box over SSH, and its tasks stop when your Mac sleeps. `prized agents run chatgpt` refuses and says so; for a session that survives a closed laptop, run `prized agents run codex`. Setting the app up is [Codex remote](/docs/codex).
## See what is set up [#see-what-is-set-up]
```bash
prized agents ls
```
One row per agent: installed and signed in on your Mac, installed and signed in on the box, MCP servers found, and where it is running on the box. Detection is read-only, and an agent you started in any session shows up, whatever the session is named. Takes `--json`.
## Hand credentials to the box [#hand-credentials-to-the-box]
```bash
prized agents handoff claude codex
```
This copies the named agents' sign-in and MCP configuration from your Mac to the box, asking first and listing what would travel; `prized setup` runs the same handoff as one of its steps. It is a one-shot copy, not a sync: change your MCP config on the Mac and re-run it. `--gh` also brings your GitHub CLI token and git identity; `--install-cursor` installs Cursor's CLI on the box first. What travels per tool, and the manual fallback, are in [Credentials](/docs/credentials).
## Several agents at once [#several-agents-at-once]
The default is one session per agent, named after it: `claude`, `codex`, `cursor`. Each can work in its own project via `--dir`. For a second concurrent run of the same agent, name the session yourself:
```bash
prized agents run claude --session claude-api --dir ~/code/api
prized agents run claude --session claude-web --dir ~/code/web
```
`prized ssh --ls` shows what is running where.
## Bring your own agent [#bring-your-own-agent]
The handoff covers the four agents above, but the box is a normal Linux machine, so any CLI agent runs on it. Pick `other` in setup's agent step and it prints this same pattern with your box's name filled in:
1. Open the box: `prized ssh` (wakes it if it is asleep).
2. Install the agent's CLI inside that shell, following its own instructions.
3. Sign in inside the box session. The credential lands on the box disk and stays there, so this is once per box, not once per session; Prized's control plane never sees it.
4. Run it detached so it survives your closed laptop: `prized ssh -s myagent` opens a named tmux session to start it in, or start it from any box shell with `tmux new-session -d -s myagent 'the-agent'`. Reattach later with `prized ssh -s myagent`.
For an agent that wants an API key, prefer the dashboard's [Connectors](/docs/connectors) over pasting the key into a file: the box gets a placeholder it can use, and the real value never touches its disk. Sessions, `prized ssh --ls`, and reattach work the same as for the built-in four; the handoff and `prized agents run` do not know the agent, so signing in and starting it stay yours.
## Review from your Mac [#review-from-your-mac]
For a synced project, the agent's edits stream into the project's folder on your Mac as it works (`~/Prized/` by default; the folder itself when synced in place), so you read the diff in your own editor with your own git tools. This is also why [sync](/docs/sync) lets the box win conflicts: a stray local save should not revert an agent's work, and that matters most for a folder synced in place. A project [cloned on the box](/docs/sync#add-a-project) has no mirror, so nothing streams: review it over git, with the agent pushing from the box and you pulling or fetching on your Mac.
Agents use the credentials on the box; `prized setup` or `prized agents handoff` puts them there, see [Credentials](/docs/credentials). For API keys an agent should use but never read, use Secrets.
> An agent on your Mac can also do the Prized setup itself: paste the prompt from [Agent setup](/docs/agent-setup). For driving the CLI from scripts or agents, every command speaks JSON; see [the CLI page](/docs/cli#for-agents-and-scripts).
---
# Codex remote
> Add your box as an SSH host in the ChatGPT desktop app and Codex runs its tasks on the box, with every edit syncing back to your Mac as it lands. One command sets the connection up.
URL: https://prized.dev/docs/codex
## What the app needs [#what-the-app-needs]
The ChatGPT desktop app can point Codex at an SSH host instead of the Mac it runs on: the app starts a Codex server on the host over SSH, and every task in that project reads files, writes changes, and runs commands there. It asks three things of the host:
* Plain `ssh` reaches the host from the Mac running the app.
* The `codex` command is on the host's PATH in a login shell. Codex comes preinstalled on every box.
* Codex is signed in on the host.
## Connect the box [#connect-the-box]
```bash
prized setup --agent chatgpt
```
One command covers all three. It runs the Codex handoff, copying your Mac's Codex sign-in and MCP config to the box (see [Credentials](/docs/credentials)), and then, with your ok, names the box as a concrete `Host` alias in `~/.ssh/config` itself. That last part matters because the app only lists concrete `Host` aliases it finds in that file, and Prized normally keeps its stanza behind an `Include` line the app may not follow. The alias is a small managed block, fenced with markers so it can be removed cleanly, placed below the Include line so Prized's stanza still supplies the tunnel, identity, and host-key settings:
```bash
# what the managed block amounts to, below the Include line
Host box-3fa9
HostName box-3fa9
```
Editing `~/.ssh/config` is a change to a file you own, so an interactive setup asks before writing it, and `prized agents handoff chatgpt` does the same on its own. In `--json` or `--non-interactive` runs nothing prompts: naming the agent with `--agent chatgpt` is the consent for the alias write.
Then, in the ChatGPT desktop app, open Settings > Connections and add the box under SSH hosts; it shows up under its hostname. Pick a project folder on the box: a synced project lives at `~/code/`. You can confirm the plain connection first from a terminal (`ssh box-3fa9`; the hostname is in `prized status` and on the dashboard).
New tasks in that project now run on the box. Because the folder is synced, the edits stream into the project's folder on your Mac (`~/Prized/` by default, your own folder when synced in place) as the task works, so you review the diff locally like any other agent's work; see [Agents](/docs/agents).
## From your phone [#from-your-phone]
With the connection in place, the ChatGPT mobile app can start, steer, and review Codex tasks on the box from anywhere. OpenAI gates this by rollout and workspace settings, so check Settings > Connections in the app if you do not see it. One limit: tasks on an SSH host cannot hand off to Codex's own cloud environments.
## Wake and sleep: the caveats [#wake-and-sleep-the-caveats]
Two of them, both about who owns the connection.
**Wake the box first.** The app connects with plain `ssh`, which does not wake a suspended box the way `prized ssh` does. If the box is paused, resume it from the dashboard or run `prized ssh` once, then connect.
**The app stops when your Mac sleeps.** The desktop app owns the SSH connection, and OpenAI tells you to keep that computer awake and online, so a sleeping Mac or a closed app ends the task. For an agent that keeps working with the laptop closed, start Codex detached on the box instead:
```bash
prized agents run codex
```
The session is born on the box, so nothing about your Mac's state can end it; see [Agents](/docs/agents).
---
# Boxes
> A box is a dedicated Linux machine in the size you pick, from Nano to Extra Large. Create and manage boxes on the dashboard; connect to them with the CLI.
URL: https://prized.dev/docs/boxes
## Create [#create]
Create boxes from the [dashboard](/dashboard); the first one comes from onboarding, which offers the same choice of size. A new box boots in about a minute. Pick a size per box: the fleet can mix sizes freely, and each one meters at its own hourly rate, see [Billing](/docs/billing). A size the balance could not run for four hours is listed but cannot be picked; add funds and it unlocks, and a funded balance is required before anything provisions. With [overage](/docs/billing#overage) switched on, nothing is blocked: usage past your credit bills with the next invoice instead.
## States [#states]
| State | Meaning |
| ------------ | ------------------------------------------------------------------------------------------- |
| running | Up and reachable. `prized ssh` lands in your session. |
| provisioning | Being created or booted. About a minute. |
| suspended | Paused. Compute is stopped; the disk stays. |
| waking | Coming back from a pause. |
| deep sleep | Suspended over 14 days: the disk is snapshotted and parked. Waking takes a few minutes. |
| resizing | Changing size. Returns to running. |
| degraded | The box stopped reporting. It reboots itself and recovers; check the dashboard if it stays. |
## Pause and resume [#pause-and-resume]
Pause from the dashboard. The disk always survives a pause, on every size: files, installed tools, and git state are exactly where you left them, and billing drops to the sleep rate the moment you ask.
What happens to running processes depends on the size. Nano through Small boxes pause with a **memory snapshot** (hibernate): RAM is written to the encrypted disk, and resume restores it, so processes, tmux sessions, and half-finished builds pick up exactly where they left off. Medium and larger boxes carry too much RAM to snapshot quickly, so they take a clean stop instead: files survive, processes restart on resume.
You rarely resume by hand. `prized ssh` wakes a suspended box on connect and prints progress while it comes up.
## Auto-pause [#auto-pause]
A box can pause itself. On the box's dashboard page, set **Auto-pause** to a window from 30 minutes to 24 hours, and the box pauses on its own once nothing has used it for that long. It is off by default and set per box.
The box judges idleness itself, so real work keeps it awake: typing or output in any terminal session, sustained CPU (builds, agents, test loops), and sustained network traffic all count as use. An agent grinding away in a detached session keeps the box up; a forgotten shell prompt does not. The shortest window is 30 minutes because that is how long the box waits before it calls itself idle at all. While a window is set, the box page shows how long the box has been idle so far.
An auto-pause is exactly a pause: billing drops to the sleep rate the moment it lands, the disk keeps everything, and what happens to running processes depends on the size, exactly as above. The box page's event list records each one. And since `prized ssh` wakes a suspended box on connect, the whole rhythm is hands-off: close the laptop and the box winds down on its own; type `prized ssh` tomorrow and it comes back.
## Resize [#resize]
Resize from the box's dashboard page. The box stops, changes size, and starts again, files intact. Sizing up also grows the disk to the new size during that same restart, so the extra space is there when the box comes back. Sizing down keeps the disk you have — disks never shrink — and it keeps costing its own sleep rate. Billing follows from that moment on: the box meters at the new size's rate, with nothing to prorate. You can resize to any size your balance can keep running.
Rarely, AWS makes a just-grown disk wait about six hours before it can grow again. If that window blocks a resize, the resize still lands at the new CPU and memory, and the disk grows by itself soon after — the extra space then shows up the next time the box restarts.
## Snapshots [#snapshots]
Snapshot a box's disk from the dashboard, and restore a snapshot into a new box whenever you want a copy of that moment. Snapshots are also your backups, so take one before risky changes. Synced projects already live on your Mac as well.
## Environments [#environments]
An environment is a named starting point for new boxes: environment variables plus a setup script that runs on first boot. Define one on the dashboard and pick it at create time. Editing an environment never touches a running box.
## Several boxes [#several-boxes]
Every box has a hostname: generated, like `box-3fa9`, unless you name it at create time. A name you pick has to read like a hostname: lowercase letters, digits and hyphens, starting and ending with a letter or digit, up to 32 characters. Anything else is refused, because the name also tags this box's synced projects so they stay separate from another box's. `prized ssh box-3fa9` connects to any of your boxes, and forwards that box's ports for the life of the session. Sync, status, and automatic port mirroring follow the box you set up with `prized setup`; to make a different box the default, run `prized init --force` and pick it.
The daemon serves one box at a time. If you point the CLI at a config for another box (`--config ` or `PRIZED_CONFIG=`) while the daemon is running for your default box, every command notices that the daemon serves a different box and works directly with the box you asked for, printing one line on stderr: `warning: prizedd is serving box "box-3fa9", not "box-71c2" — using direct mode for box-71c2 (the daemon serves one box at a time)`. You never need `--direct` for this. That covers `prized status`, `prized sync ls/add/rm/pause/resume/flush/repair`, `prized ports ls`, `prized up`, and the snapshot, restore, and resize flows.
Two things work differently:
* `prized ports toggle` is refused (exit 4). Port mirrors live inside the daemon, and the running daemon's mirrors belong to the other box; `--direct` cannot help, since there would be no proxy to toggle. To mirror the second box's ports, make it the default with `prized init --force`.
* `prized doctor` reports a warning on its daemon check, naming both boxes, instead of a clean pass.
`prized status` still lists the daemon as running and names the box it serves, and `prized daemon status` does the same. Each box's synced projects stay separate: sync commands only ever touch sessions belonging to the box in the config you pointed at, and the running daemon leaves the other box's projects out of its own listings and never touches them. One consequence: two boxes cannot both sync a project under the same name at once. The second `prized sync add` refuses and asks for `--name`.
## Delete [#delete]
> Deleting a box is permanent: the machine and its disk are gone. Anything you synced is already on your Mac.
---
# Credentials
> Prized does not store your dev credentials. setup hands your agents' sign-ins from your Mac straight to the box over the SSH tunnel; the control plane never sees them, and they stay on the box.
URL: https://prized.dev/docs/credentials
## Hand them over from your Mac [#hand-them-over-from-your-mac]
```bash
prized setup
# or, for the agents alone:
prized agents handoff claude codex
```
If you are already signed in to a coding agent on your Mac, the handoff moves that sign-in to the box so you never retype an OAuth flow. The transfer runs from your Mac to the box directly over the existing SSH tunnel: the control plane never sees, stores, or proxies a credential, the same trust surface as signing in on the box yourself. Consent is per concern, never blanket: it asks per agent, listing the exact files and remote commands, and the GitHub token (`--gh`) and the Cursor installer (`--install-cursor`) each need their own yes. Config files travel as-is, and some can embed API keys (an agent's settings file, MCP server definitions); the prompt flags those before anything is copied.
Per tool:
* **Claude Code.** Its sign-in does not survive a file copy, so the handoff runs `claude setup-token` on your Mac (a browser sign-in that mints a long-lived token; needs a Pro, Max, or Team plan) and places the token on the box. Your MCP servers and settings are carried over alongside it. If that command cannot open a browser, it prints a URL to visit; the URL is shown to you, the token it prints is not.
* **Codex.** `~/.codex/auth.json` and `config.toml` (which holds the MCP servers) are copied; this is Codex's own documented path for headless machines.
* **Cursor.** MCP and CLI config are copied. Sign-in is guided on the box: Cursor's macOS credentials live in the Keychain, which Prized never reads, so `agent login` prints a URL you open on your Mac.
* **GitHub.** With `--gh`, your `gh` token is piped to `gh auth login --with-token` on the box, never through a command line, and your git name and email are copied if the box has none.
MCP servers whose own sign-in cannot travel are reported per server as needing re-auth, with the in-tool command to run; nothing fails silently. A server whose auth Prized cannot account for either way is reported `unknown` rather than `ok`: the file it would have travelled in exists on the box, but nothing in it names that server. Servers configured for one project rather than globally get their own rows, marked `[project]`. The handoff is a one-shot copy: re-run it after changing MCP config on the Mac.
The report says what was actually checked, and only that:
| Result | What it means |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `ok` | the tool answers that it is signed in, and for GitHub that the box's account is the same one your Mac uses |
| `needs-reauth` | the material landed but the check disagreed, could not run, or found a different account signed in |
| `manual` | there was nothing to transfer; the printed steps sign you in on the box |
| `needs-rerun` | skipped on purpose (the agent was running); re-run the handoff afterwards |
Two consequences worth knowing. A box already signed in to GitHub as another account never reads as success, because the accounts are compared, not just the presence of a login. And Claude Code has no scriptable status command, so a token sitting on the box is reported as exactly that, never as a verified live sign-in.
The handoff never writes a credential *through* a symlink. A link would put a fresh sign-in wherever it points, which on a box with a synced project folder can mean the credential lands in your repo. So if `~/.codex`, `~/.cursor`, `~/.claude`, `~/.claude.json` — or a directory above one of them — is a symlink on the box, one of two things happens. A symlinked **directory** stops the transfer, which names the path; replace it with a real directory (or move the target out of the synced tree) and re-run. A symlinked **file** is replaced by the real file, so the credential lands where it belongs and the link is gone. Either way nothing is written to what the link pointed at. If you manage the box's home with dotfiles, this is the case to know about.
The order inside one run is fixed: anything that installs software on the box (the Cursor installer) runs before any credential lands there, and the GitHub token goes last. That holds even when a `--clone` project needs GitHub auth to clone, which pulls the token step earlier: the installer moves ahead of it rather than running on a box that already holds your token.
## Or sign in on the box [#or-sign-in-on-the-box]
```bash
prized ssh
gh auth login
claude
```
The manual path still works, and it is what the handoff falls back to when there is nothing to transfer: one command per tool, run in a shell on the box, `gh auth login` for GitHub, `claude` for Claude Code, `codex` for Codex. Each stores its credential on the box the way it would on any machine. Since disks persist, either way you do this once per box.
## Secrets for agents [#secrets-for-agents]
For API keys that agents should use but never read, the dashboard has Secrets. You paste a value once; it is encrypted at rest and cannot be read back from the dashboard. Processes on the box see only a placeholder. When one calls an HTTPS host you allowlisted for that secret, the box swaps the real value into the request headers on the way out. Plain HTTP to an allowlisted host is refused, so a brokered value is never injected into cleartext transport.
So the key never appears in env files, shell history, or logs, and a leaked placeholder is worthless. The real value lives in the memory of the box's broker process, not on its disk. For common provider presets, see [Connectors](/docs/connectors).
## The machine itself [#the-machine-itself]
Every box is a dedicated machine; no other customer can log in to it or read its disk. Traffic between your Mac and the box runs over an encrypted tunnel, and nothing on the box is reachable from the internet except that tunnel's endpoint. SSH and your dev ports are never exposed publicly.
## What Prized itself stores [#what-prized-itself-stores]
Signing in with `prized login` writes a CLI token and an SSH identity to `~/.config/prized` on your Mac. The token authenticates you to the control plane, where boxes are created and managed. Your dev credentials never leave your machines: the handoff moves them from the Mac to the box, and the control plane is not on that path.
While you are signed in, the CLI also reports which commands ran (name, version, OS, duration, exit code) so we can find and fix problems. It never reports arguments, paths, or file contents. See [CLI: usage telemetry](/docs/cli#usage-telemetry) for the opt-out.
---
# Connectors
> Mount brokered credentials for ClickHouse, OpenAI, Anthropic, GitHub, or Slack into a dev box without writing the real value to its disk.
URL: https://prized.dev/docs/connectors
## Connect a service [#connect-a-service]
Open **Connectors** in the dashboard and choose a provider; on its connect page, pick a box and paste the credential. Prized creates an encrypted secret with the provider host allowlist and mounts it under the conventional env name.
| Connector | Default env name | Allowed host |
| ---------- | --------------------- | ------------------------------ |
| ClickHouse | `CLICKHOUSE_PASSWORD` | The HTTPS endpoint you enter |
| OpenAI | `OPENAI_API_KEY` | `api.openai.com` |
| Anthropic | `ANTHROPIC_API_KEY` | `api.anthropic.com` |
| GitHub | `GITHUB_TOKEN` | `api.github.com`, `github.com` |
| Slack | `SLACK_BOT_TOKEN` | `slack.com` |
The box sees a placeholder in that env variable. The broker substitutes the real value only when an HTTPS request sends that placeholder unchanged in a request header to the allowed host.
## ClickHouse [#clickhouse]
Enter the HTTPS endpoint, such as `https://abc.clickhouse.cloud:8443`, and the password. Keep the endpoint, username, and database in your project's normal non-secret config. The connector mounts only the password.
A direct HTTP-interface check looks like this:
```bash
curl -sS "$CLICKHOUSE_URL/?database=$CLICKHOUSE_DATABASE" \
-H "X-ClickHouse-User: $CLICKHOUSE_USER" \
-H "X-ClickHouse-Key: $CLICKHOUSE_PASSWORD" \
--data-binary 'SELECT 1'
```
Plain HTTP endpoints are refused. A brokered password is never sent over cleartext transport.
## Client compatibility [#client-compatibility]
The client must send the env value unchanged in an HTTPS request header. Most bearer-token SDKs do this. A client that transforms the value first, for example by building a Basic-auth base64 string inside the box, prevents exact placeholder substitution. Prefer a raw token header, or store the already transformed header value as the connector credential when the upstream supports it.
## Rotate or remove [#rotate-or-remove]
Connectors use the same broker as **Secrets**. Rotate or delete the generated credential under **Secrets**. Open the box's **Secrets** tab to inspect or remove its env binding.
---
# CLI
> The Prized CLI is a thin client over the Mac daemon and the box agent; add --help to any command for full flags. Every non-interactive command also takes --json and prints exactly one JSON object.
URL: https://prized.dev/docs/cli
## Commands [#commands]
| Command | What it does |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prized login` | Authenticate the CLI. Opens the dashboard to mint a token, then sets up your SSH identity. |
| `prized init` | Adopt the box on your account: write the config, install the SSH stanza, start the daemon. |
| `prized setup` | The whole onboarding in one pass: machine, health check, project sync (`[PATH]`, in place when the path is outside `~/Prized`; `--copy` syncs a copy under `~/Prized` instead; `--clone` clones the repo onto the box with no sync, so it never shows in `prized sync ls`), agent handoff (`--agent`, `--gh`, `--install-cursor`; agents you picked before are remembered, `--no-agents` opts out), detached session (`--start`). Safe to re-run; it converges instead of conflicting. |
| `prized up` | Start the box and reconnect everything, from cold. Reports paused syncs; `--resume` resumes them. |
| `prized ssh` | Connect to the box in a persistent tmux session. Wakes a suspended box first. Files dragged into the window upload to the box. |
| `prized mosh` | Same session over mosh: instant echo, survives roaming and sleep. Needs mosh installed locally. |
| `prized sync` | Add (`--local` syncs a folder of your own in place), list, pause, resume, flush, repair, and remove synced projects. |
| `prized mount` | Mount a box in Finder as a live volume until interrupted; nothing is copied locally. Experimental. |
| `prized agents ls` | One row per coding agent: installed and signed in on the Mac and the box, MCP servers, where it runs. |
| `prized agents handoff` | Copy the named agents' sign-in and MCP config to the box; `--gh` and `--install-cursor` extend it. One-shot; re-run after config changes. |
| `prized agents run` | Start an agent detached in a tmux session on the box: `--session`, `--dir`, `--attach`, `-- ARGS`. |
| `prized status` | Box, sync, ports, and daemon state at a glance. `--watch 2s` to keep it open. |
| `prized ports` | List box listeners and their mirror state; toggle a port on or off. |
| `prized proxy` | Forward one box port to localhost until interrupted. |
| `prized doctor` | Run the full health check. `--fix` applies the safe repairs. |
| `prized snapshot` | Snapshot the box disk without stopping it; `ls` lists snapshots, `restore` rolls back. Needs `[aws]` configured. |
| `prized resize` | Change the box size in place: pause syncs, stop, modify, start, resume. Needs `[aws]` configured. |
| `prized version` | Print client, daemon, and agent versions. |
| `prized update` | Update prized and the daemon in place from verified releases. |
| `prized daemon` | Manage the Mac daemon: install, uninstall, start, stop, restart, status, logs. |
| `prized agent upgrade` | Upgrade the agent on the box. It normally updates itself. |
| `prized mutagen ensure` | Fetch Prized's managed copy of Mutagen. The installer, `init`, and `doctor --fix` run it for you. |
> You can also create, resize, and delete boxes from the [dashboard](/dashboard). See [Boxes](/docs/boxes).
## Global flags [#global-flags]
| Flag | What it does |
| --------------- | ---------------------------------------------------------------------------------- |
| `--json` | Machine output: exactly one JSON object on stdout. Interactive commands reject it. |
| `-y, --yes` | Assume yes for confirmations. |
| `-q, --quiet` | Suppress non-essential output. |
| `-v, --verbose` | Verbose output; repeat for wire detail on stderr. |
| `--timeout` | Per-request network timeout, default 10s. |
| `--no-color` | Disable ANSI color. `NO_COLOR` is honored too. |
## For agents and scripts [#for-agents-and-scripts]
A failing `--json` command prints:
```json
{ "ok": false, "error": { "code": "CHECK_FAILED", "message": "…", "hint": "…" } }
```
On success the object is `{"ok": true, ...}` with the payload inline. `error.code` maps 1:1 to the exit code, and both are a stable contract:
| Exit | `error.code` | Meaning |
| ---- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
| 0 | | Success. |
| 1 | `INTERNAL`, `AWS_ERROR` | Internal or unexpected error. |
| 2 | `USAGE` | Usage error. |
| 3 | `BOX_UNREACHABLE` | Box unreachable. |
| 4 | `DAEMON_UNAVAILABLE` | Daemon required but unavailable. |
| 5 | `CHECK_FAILED` | A precondition failed; the `hint` says what to do. |
| 6 | `CONFLICT` | Already exists: project name, port, config. |
| 7 | `PARTIAL` | A batch partly failed: some items of a `--all` run or an `agents handoff` succeeded, others did not. |
| 8 | `AUTH` | Not signed in or token rejected; run `prized login`. |
| 9 | `MISSING_DEP` | A dependency is missing; `prized doctor --fix` usually helps. |
| 10 | `DECLINED` | You declined a confirmation. |
| 130 | | Interrupted. |
`prized ssh` is the exception: after connecting, its exit code is whatever the remote command returned.
Sign-in without a browser: `prized login --token dcp_…` takes a CLI token minted in the dashboard directly, and is the only login form `--json` accepts. To hand a whole setup to an agent instead of scripting it yourself, see [Agent setup](/docs/agent-setup). The docs themselves are mirrored as plain text at [/llms.txt](/llms.txt) (index) and [/llms-full.txt](/llms-full.txt) (full content) for agents to read.
## Files [#files]
| Path | What lives there |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| `~/.config/prized/config.toml` | The config: box name, sync projects, port policy, preferred agents (`[agents]`). |
| `~/.config/prized/` | CLI token, SSH identity, and per-box certificates. |
| `~/Prized/` | The default local twin of synced projects; one added with `--local` lives at its own path instead. |
| `~/.ssh/config.d/prized` | The SSH stanza that makes `ssh box-3fa9` work everywhere. |
| `~/Library/Logs/prized/` | Daemon logs. |
An install that predates the rename keeps its old paths (`~/.config/doppel`, `~/Doppel`, `~/.ssh/config.d/doppel`) and everything keeps working; see [doppel is now Prized](/docs/rename).
## Updates [#updates]
`prized update` replaces the CLI and daemon in place from signed releases.
`prized status` and `prized version` note when a newer release exists; the
check is a cached, sub-second probe you can turn off with `check = false`
under `[update]` in the config. If your installed CLI falls below the
minimum the API supports, commands exit with code 5 and a `prized update`
hint until you update.
## Usage telemetry [#usage-telemetry]
When you are signed in, the CLI records which command ran, its version, OS,
duration, and exit code, and sends those counts to Prized in occasional
batches. It never records arguments, flags, paths, or file contents, and it
sends nothing while you are signed out.
Turn it off either way:
```bash
# in ~/.config/prized/config.toml
[telemetry]
enabled = false
```
```bash
# or per shell
export PRIZED_NO_TELEMETRY=1
```
This switch covers the CLI only. For what the website and dashboard record,
and how to turn that off, see [Privacy](/docs/privacy).
---
# Billing
> Pick a monthly plan from $10 to $1,000. It lands as credit every cycle, boxes bill by the hour against it, and unused credit rolls over up to two months of your plan.
URL: https://prized.dev/docs/billing
## How it works [#how-it-works]
A plan is just how much money you put in each month. Subscribe at any rung of the ladder, from $10 to $1,000, and every billing cycle exactly that much credit lands in your balance. Every box you own meters against that balance:
* **Awake**, a box costs its monthly price spread over a 730 hour month. A Small is $100 a month, so it bills $0.137 an hour.
* **Asleep**, it costs $0.0001 per GB hour of the disk your box actually has, which is what keeps your files, ports and processes exactly where you left them. A Small asleep for a whole month is about $22. A box that kept a bigger disk, sized down after growing or restored from a large snapshot, sleeps at that bigger disk's rate, and pays the same per-GB rate for the extra disk while awake.
Pausing is how you keep the money: pause from the dashboard, or switch on [auto-pause](/docs/boxes#auto-pause) per box and it drops to the sleep rate by itself once it has sat idle for the window you pick. `prized ssh` wakes it when you come back.
Metering runs by the second and is quoted by the hour. Unused credit rolls over, up to two months of your plan: when a cycle's credit lands, anything above that cap lapses (it shows in your activity as its own line). Credit you bought as a one-time top-up is protected from that trim for two months after buying it. If you find yourself brushing the cap every month, a smaller plan fits you better; there is nothing else to configure.
Each plan is priced to run one size around the clock: the $10 plan runs a Nano, the $100 plan a Small, the $1,000 plan an Extra Large. The credit is yours to spend on any mix, though: a $100 plan also runs a Medium for a working day plus a Nano that never sleeps.
## Sizes and rates [#sizes-and-rates]
The live shape and price table is at https://prized.dev/pricing.
The last column is both the most a box can cost in a month and the plan that runs it around the clock. A comparison against renting the same machine elsewhere is on the [pricing page](/pricing).
## Choosing and changing the plan [#choosing-and-changing-the-plan]
Pick a plan during onboarding or from the dashboard's Billing page. Payment goes through Stripe Checkout, cards only, and the first cycle's credit lands before you are back on the dashboard.
You do not have to choose one up front. Signing up, installing the CLI and browsing the dashboard all work before you pay. Choosing a plan is also what starts your first box: the rung you pick is the size that runs around the clock on it, so there is no separate machine to configure. Every size after that is yours to create, resize and delete as you like.
Change the plan from the same page whenever you like:
* **Upgrading** bills the prorated difference immediately and lands it as credit right away, then the new amount bills from the next cycle. Need more compute today: upgrade, and the money is spendable within a minute.
* **Downgrading** changes what the next cycle bills. Nothing is taken back; this cycle's credit stays yours.
* **Cancelling** stops the plan at the period's end. Credit already landed keeps working until it is spent.
The Billing page leads with the two numbers that matter: what is in the account, and how long that lasts at your current burn, the balance divided by what the fleet is costing right this second. That answer is exact, and optimistic when the fleet happens to be asleep: wake everything up and the runway shortens accordingly.
If your live boxes all fit a smaller plan, the page says so right above the picker, with the plan that covers them. Downgrading is never penalized: it changes what the next cycle bills and takes nothing back.
## Topping up [#topping-up]
Burned through a cycle early and don't want a bigger plan? If you've switched [overage](#overage) on, you don't have to do anything: usage past your credit just bills with the next invoice. Otherwise, add credit once from the Billing page: pick an amount from $10 to $250, pay by card, and the money is in your balance before you are back on the page. A top-up never changes what your plan bills; it is simply more credit in the same balance, spent by the same meter. If it keeps happening, upgrading the plan is usually the better deal, and the create and resize flows will already be suggesting it.
## When we tell you [#when-we-tell-you]
A prepaid balance goes down quietly between cycles, so three things watch it for you:
* **The dashboard** shows a banner on every page once there is less than two days of credit left at your current rate, a different one while you are in overage, and a third if boxes have been suspended.
* **`prized status`** prints a credit line when the balance is running low, so you see it without leaving the terminal.
* **Email**: twice on the way down, once when you are at a quarter of what the last cycle left you and again at a tenth; once when your balance crosses into overage; and once if boxes are ever paused. If your plan's payment fails, you get a mail for that too. Every one of them links straight to your billing page.
If you signed up and never started a plan, you may get at most two reminders about it, and then nothing further.
## Overage [#overage]
Overage is **off by default**: out of credit means boxes pause, and nothing ever bills past what you put in. Flip the switch on the Billing page and running out of credit stops nothing instead. The meter keeps billing past zero at the same hourly rates, and the amount below zero is your overage: it is added to your next invoice automatically, as its own line beside the plan, and collected in the same charge. No markup, and prepaid credit (your plan's drop, or a top-up) always spends first. Turn it off again any time and the balance is the hard stop once more.
With it on, you will know when it happens: the dashboard shows an overage banner, the balance on the Billing page reads negative with the exact figure, and we email you once when you cross. If you would rather not carry overage into the invoice, a top-up or an upgrade lands credit immediately and pays it down on the spot.
Two things end overage's grace on their own: a failed payment and a cancelled plan. If a cycle's charge does not collect, overage pauses with it — the balance becomes the hard stop again until a payment goes through. And if your plan ends while the balance is negative, the outstanding overage bills once, on a final invoice against the same card.
## Running out [#running-out]
With overage off (the default), and always without a plan or while a payment is failing, the balance is the hard stop: when it reaches zero, boxes suspend. They are not deleted:
* Disks are kept, so your work, your installed tools and your git state are all still there.
* A plan's next cycle, an upgrade, or a one-time top-up starts them again from the dashboard. We never start them for you, because we will not spend your money on your behalf.
* Suspended boxes keep metering their disk at the sleep rate, which is what a stopped box actually costs us. With overage off, usage the balance cannot cover is written off rather than turned into a debt.
> Nothing is deleted automatically. A balance that stays empty for a long time puts the account on a reclaim list we work through by hand, and we contact you before any disk is released.
## Starting and resizing boxes [#starting-and-resizing-boxes]
A create, a wake or a resize needs enough balance to run the resulting fleet for four hours. It is not a charge; it is a check, so a box that starts is a box that will still be there after lunch. If the check refuses, the message says exactly what the fleet would burn and what the balance would have to be.
Resizing takes effect from that moment on, at the new rate. The plan does not care which boxes spend its credit. If a size-up would make your fleet cost more around the clock than your plan puts in each month, the resize dialog says so and offers the covering plan as one extra click, quoting the exact amount your card is charged today: the prorated difference bills immediately and lands as credit right away, then the box resizes. It is only an offer; you can always just resize and spend the balance down faster.
Creating a box works the same way, with the default flipped: when the new box would outgrow your plan, the create form pre-selects the covering plan and the button reads "Create and switch to $X/mo". Uncheck the offer to create the box on your current plan. Either way nothing charges without the page saying so first, and the prepaid balance stays the only thing that actually gates a box.
If you have no plan yet and nothing left to spend, the same spot offers your first plan instead: the button takes you through checkout, the first cycle's credit lands during the redirect, and you come back to the form with your shape still selected, one click from the box.
## Failed payments [#failed-payments]
If a cycle's payment does not go through, nothing is suspended by the failure itself: no credit landed, so the balance simply is not refilled and boxes keep running on what remains. The failure does switch overage off, though — a card that just bounced is not one to keep billing against — so from there the balance is the hard stop until a payment collects. Stripe retries the card on its own schedule, the dashboard shows a banner, and we email you once. Update the card in the Stripe portal, linked from the Billing page, and the charge retries on its own.
Money that goes the other way is symmetrical: a refund we issue, or a payment your card issuer pulls back (a dispute), takes the credit it bought back out of the balance, and a dispute also pauses the plan's billing until it resolves.
## Receipts [#receipts]
Every cycle produces a Stripe invoice you can download. The Billing page lists recent activity: each cycle's credit and one usage line per hour of metering. Card details, invoice history and receipts live in the Stripe portal, linked from the same page.
## Custom plans [#custom-plans]
If the ladder does not fit — a startup deal, an amount between rungs, something bigger than the largest plan — email the support address shown on https://prized.dev/docs/troubleshooting and we will send you a link. Opening it shows your plan and subscribes you at that amount in one click; if you already have a plan, the same link moves it. From then on it behaves exactly like any other plan: the amount lands as credit every cycle, and you change or cancel it from the Billing page. Custom links expire after 30 days, so ask for a fresh one if yours has lapsed.
---
# Troubleshooting
> One command diagnoses the whole chain; config, auth, tunnel, SSH, sync, daemon, and the box agent. Start here.
URL: https://prized.dev/docs/troubleshooting
## Run the doctor [#run-the-doctor]
```bash
prized doctor --fix
```
`doctor` prints one line per check with a hint under anything that fails. `--fix` applies the repairs that are safe to automate, then re-runs. For a bug report, `prized doctor --bundle` writes a diagnostics tarball; nothing leaves your Mac.
## Common cases [#common-cases]
| Symptom | Try |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Box shows unreachable | `prized status` to confirm, then `prized ssh`: a suspended box wakes on connect. Still down? Check the box on the dashboard. |
| A port is not on localhost | `prized ports ls` shows every listener and why one is not mirrored. A toggled-off port stays off until you toggle it back. |
| Sync seems stuck | `prized sync ls` for the state, `prized sync flush` to force a cycle, `prized sync repair myproject` if a session halted. |
| Mutagen reported missing | `prized doctor --fix` fetches Prized's managed copy of Mutagen; `prized mutagen ensure` does the same. |
| Daemon not running | `prized daemon restart`, then `prized daemon logs` if it will not stay up. |
| "the running daemon serves a different box" | You set up a second box, or switched the default one, while the old daemon was still running. `prized setup` restarts it for you; `prized daemon restart` does it directly. Until it restarts, connections still work over a slower in-process tunnel. |
| doctor warns the daemon serves another box | Expected when you point the CLI at a second box's config: the daemon serves one box at a time, so commands work directly with the box you asked for. `prized init --force` makes it the default if you want the daemon on it. |
| CLI feels outdated | `prized status` and `prized version` tell you when an update exists; `prized update` installs it, verified. |
| `prized: command not found` | Your install predates the [rename](/docs/rename). Run `doppel update` once, or re-run the install script; either installs `prized` and keeps `doppel` working as an alias. |
| Both `doppel` and `prized` are installed | Expected after updating across the [rename](/docs/rename): `doppel` is a symlink to `prized`, kept so existing scripts and launch configs never break. Use whichever you like; there is nothing to clean up. |
| Every command exits with code 5 and an update hint | Your CLI is older than the minimum the API supports. Run `prized update` once and everything works again. |
| macOS asks again for folder access after an update | `prized update` to the latest release and approve once more. Releases are now signed with a stable Developer ID, so macOS remembers the grant across future updates; older unsigned builds re-prompted every time. |
## Still stuck [#still-stuck]
Email the support address shown on https://prized.dev/docs/troubleshooting with the doctor output.
---
# doppel is now Prized
> Same product, new name. The command is prized, the daemon is prizedd, and new installs use Prized-named paths. Existing installs keep working with nothing to migrate.
URL: https://prized.dev/docs/rename
## What changed [#what-changed]
| Before | Now |
| -------------------------------- | ------------------------------ |
| `doppel` (CLI) | `prized` |
| `doppeld` (Mac daemon) | `prizedd` |
| `doppel-agent` (box service) | `prized-agent` |
| `~/.config/doppel/config.toml` | `~/.config/prized/config.toml` |
| `~/Doppel` (sync root) | `~/Prized` |
| `DOPPEL_*` environment variables | `PRIZED_*` |
| doppel.prized.dev | prized.dev |
| api.doppel.prized.dev | api.prized.dev |
The old addresses still work. `doppel.prized.dev` redirects to `prized.dev`, so
bookmarks, saved install commands, and links from anywhere else land in the
right place. `api.doppel.prized.dev` is not a redirect but a second name for
the same API, kept because your config file names an API host and nothing
rewrites that file behind your back: a CLI that has been pointed there since
before the move keeps talking to exactly the same service. A config that still
names `doppel.prized.dev` itself is fine too — API calls on that host are
served, not redirected, so the oldest configs keep working unchanged.
One thing you will notice once: the first visit to `prized.dev` asks you to
sign in again. Browsers keep sign-ins per address, so the session you had on
the old address does not follow you there. Everything is exactly where you
left it once you sign in.
## What you need to do [#what-you-need-to-do]
Nothing, today or on any particular schedule:
* The `doppel` command keeps working. Your next `doppel update` installs `prized` and leaves `doppel` behind as an alias for it, so scripts and muscle memory both survive. Running it as `doppel` prints a one-line reminder of the new name, once per run, and is otherwise identical.
* An existing install keeps its paths: config in `~/.config/doppel`, projects under `~/Doppel`, the same daemon, sessions, and SSH stanza. Nothing is moved and no migration runs.
* Boxes update their own agent, as always.
* `DOPPEL_*` environment variables still work. `PRIZED_*` is the new form, and wins when both are set.
* Your `[controlplane].url` is left alone. If it names `api.doppel.prized.dev`, that keeps resolving; point it at `api.prized.dev` whenever you feel like it, or never.
## Switching cleanly [#switching-cleanly]
Type `prized` instead of `doppel`; that is the whole switch. All help text, docs, and examples now say `prized`.
Optionally, reinstall with the script to pick up the new names in one step:
```bash
curl -fsSL https://prized.dev/install.sh | sh
```
It installs `prized` and `prizedd`, and replaces an existing `doppel` binary with the alias. Your config and synced projects stay exactly where they are; only a fresh install (no existing config) gets the new `~/.config/prized` and `~/Prized` paths.
---
# Privacy
> What Prized records about how you use the product, and what it never records.
URL: https://prized.dev/docs/privacy
Prized collects two kinds of usage data: what the CLI does on your machine,
and how you use the website and dashboard. Neither one reads what is inside
your box.
## What is never collected [#what-is-never-collected]
Nothing from inside your box is sent anywhere for analytics:
* Source code, files, and anything else on the box filesystem
* Terminal output and shell history, including the in-browser terminal
* Secret values and environment variable values
* CLI arguments, flags, and paths
## Website and dashboard [#website-and-dashboard]
The site records page views, clicks, and a short list of named product
events: creating, pausing, resuming, resizing, and deleting a box, and
copying a CLI command. Once you sign in, those events are tied to your
account, so a broken flow can be traced to the account that hit it.
## Session replay [#session-replay]
While you are signed in, the dashboard records a replay of the interface,
which is how a confusing or broken flow gets diagnosed without a support
call. Replay is masked in your browser, before anything is sent:
* Every input and every piece of text is masked. A replay shows layout,
clicks, and navigation, never the words on the page.
* The terminal, the secrets panel, and the environment variables panel are
blocked outright. They record as empty placeholders, so nothing rendered
inside them can be recovered from a replay.
Signed-out visitors are never recorded, so browsing the marketing pages or
these docs produces no replay at all.
## Turning it off [#turning-it-off]
The site respects your browser's Do Not Track setting. With Do Not Track on,
the site records nothing: no page views, no events, no replay.
The CLI has a separate switch, covered in
[CLI: usage telemetry](/docs/cli#usage-telemetry).
## Where it goes [#where-it-goes]
Usage data goes to PostHog, which Prized uses for product analytics and for
error reports when a page throws. Events are sent directly to PostHog's US
cloud. No analytics code is ever fetched at runtime: the PostHog SDK and all
of its extensions are pinned into our reviewed build. An ad blocker may
block the analytics requests themselves; that affects our telemetry, never
the dashboard's functioning.