# Open Quick

**Drop a folder, get a secure URL your team can review — on infrastructure you own.**

One naming note so nothing is confusing: the product is **Open Quick**, the npm package is
**`oquick`**, and the command it installs is **`quick`** (with `oq` and `oquick` as aliases).

Open Quick publishes anything — markdown, HTML apps, CSVs, code, images — to your own small server
(we call it **your box**), gives you a live URL, and turns feedback into data: reviewers comment
right on the artifact with no signup, and you (or your coding agent) pull those comments back,
fix, and republish to the same URL.

## Quickstart

```bash
npm i -g oquick

quick agent equip           # teach your coding agent the whole loop (quick setup does this for you)
cd the-thing-you-made
quick setup                 # once: provisions your box (or connects to an existing one)
quick site publish          # publish/update — prints the site URL, plus a ?k= review link
quick site share the-thing  # mint the no-signup ?k= link to hand a reviewer
```

Send the `?k=` link — a new site is private, so that link is what opens it and what lets a reviewer
comment. When feedback arrives:

```bash
quick comment list         # pull it back, structured (--json for agents, --watch to stream)
```

Edit, `quick site publish` again — same URL, new version, thread continues.

## What actually happens under the hood

- **Your box** is a single small server (`ghcr.io/open-quick/quick-server`) that `quick setup`
  provisions on **your own Railway account** — it opens a browser login to Railway the first time;
  no tokens to paste, and we never see your credentials. It attaches a managed Postgres and a
  durable volume, so content and comments survive restarts.
- **One box holds all your sites.** Every folder you publish becomes a site at a stable path on the
  same box (`https://box.../you/folder/`). Publishing again adds an immutable version underneath —
  the URL never changes.
- **On your machine**, credentials and box records live in `~/.oq` (file-permission locked). A
  published folder gets a small `.oq/project.json` binding it to its box, so a bare `quick site publish`
  always knows where to go.
- Already have a box (a teammate set one up)? `quick setup --url https://that-box...` connects
  instead of provisioning.

## Who can see what (the trust model)

- **Private by default.** A newly published site is private: the bare URL shows nothing to someone who
  isn't signed in. Owners can make a site public, or set a password.
- **Sharing is a link.** `quick site share <site>` mints a no-signup link (`?k=...`). Anyone with it
  can read the site and leave comments — as a guest, with just a display name. Add `--password` to
  require a password on top.
- **Unshare = rotate.** `quick site share <site> --reset` invalidates the old link immediately; existing
  visitors lose access on their next request.
- **Public means readable, never writable.** If you make a site public, anyone can read it without a
  link — but writing a comment still requires a share link or a session.
- **Comment authorship is honest.** Signed-in authors are stamped by the server from their session;
  guests are labeled as guests. A guest cannot impersonate a member.
- Deleting a whole site/box from the CLI isn't built yet — `quick list` shows every box this machine
  owns, and a box can be removed from your Railway dashboard.

## Your agent is a first-class user (`quick agent equip`)

Open Quick isn't just a CLI you type — it's a capability your coding agent gains. The lifecycle is
five words long:

```bash
npm i -g oquick           # install
quick agent equip         # teach your agents
quick agent equip --check # "can my agent use Open Quick?" — detected agents + readiness
quick site publish        # ship + share (you or the agent)
quick agent unequip       # remove cleanly (receipt-based, byte-for-byte)
```

`quick agent equip` detects coding agents on your machine — Claude Code, Codex, OpenCode, Cursor, Gemini
CLI, Amp — and installs a skill pack in each agent's own native format, teaching the whole loop:
publish a folder, relay the review link, watch comments (`quick comment list --watch`), make the fix,
republish, reply/resolve. Agents drive the exact same CLI you do — every command works headless
with `--json`. Nothing else on your machine is touched; the receipt in `~/.oq/equip.json` makes
removal exact.

**Where the agent runs — say it plainly:** your agent always works on YOUR machine, never on the
box. The in-page "Ask my agent" panel exists only under local `quick dev` (where the page and the
agent share a machine). For a deployed box the loop is: reviewers comment on the cloud URL → your
agent watches (`quick comment list --watch`) or you pull (`quick comment list`) → it edits local files →
`quick site publish` ships the fix → reply/resolve closes the thread. A shared server that could run an
agent would be a remote-code-execution hole; this split is a security decision, not a gap.

## When something doesn't work

| Symptom | What's happening | Do this |
| --- | --- | --- |
| `Railway login timed out` / browser never opened | the one-time Railway device login didn't complete | re-run the command — it prints a fresh code + link (railway.com/activate) |
| `Railway CLI installed but is not on PATH` | npm's global bin dir isn't on your PATH | add `$(npm prefix -g)/bin` to PATH, or install Railway yourself, then re-run |
| `warning: … hasn't served yet … warming up` | the box is still booting after provision | wait ~30–60s and open the URL again — the publish itself succeeded |
| the published URL shows "Private" | that's the point — you're not signed in and have no link | send people the `quick site share` link, not the bare URL |
| `this folder is bound to … but this machine has no credentials` | the folder's `.oq/project.json` points at a box this machine never set up | publish from the machine that owns it, or delete `.oq/project.json` to start fresh here |
| need a specific/staging server image | the box image is overridable | set `QUICK_SERVER_IMAGE` (e.g. `ghcr.io/open-quick/quick-server:dev`) before `quick setup` |
| anything else | — | `quick list` shows what this machine knows; every command has `--help` |

## Staying current

The CLI prints a one-line nudge when a newer version exists; `quick update` installs it (staying on
your release channel — `@latest`, or `@next` if you installed the dev channel).

## Local, no box at all

```bash
quick dev ./folder     # serve locally with the same viewers + review overlay
```

Repository, full docs, and the server source: https://github.com/open-quick/open-quick · MIT