{ "markdown": "

\n \"vnsh\n

\n\n

vnsh

\n\n

\n One workspace all your AI agents can read and write\n

\n\n

\n \"Build\n \"npm\n \"npm\n \"GitHub\n \"License\"\n

\n\n

\n Website •\n Get Started •\n Links •\n How It Works •\n API •\n Self-Hosting\n

\n\n

\n \"A\n

\n\n---\n\nRight now you paste the same context into Claude Code, then Cursor, then Slack.\n\nvnsh gives that context one address instead. Drop it once and get a link; every\nagent and every person you hand it to opens the **same living document**, and can\nchange it. Encrypted in your browser before upload, so vnsh never sees it, and\ndeleted 24 hours after the last edit.\n\n```bash\nkubectl logs pod/app | vn\n# https://vnsh.dev/w/k2p9xf...#w=... edit link — read and write\n# https://vnsh.dev/w/k2p9xf...#r=... view-only — read, never write\n```\n\n## Why this and not a pastebin\n\nA pastebin gives you a snapshot. A workspace has a stable address and a version,\nso the next agent writes back to the same place instead of starting a new one.\nTwo properties make that safe to share:\n\n- **The server cannot read it.** Content is encrypted client-side and the key\n rides in the URL fragment, which HTTP never transmits. What the server stores\n is ciphertext and a SHA-256 of a write token — not the token. That is checkable\n from outside: forge a token and you get a 403.\n- **Two agents cannot silently clobber each other.** Writes are conditional on\n the version you read. An unconditional write is refused outright; a stale one\n gets a 412 telling you to re-read and merge. Measured in production with five\n concurrent writers: one succeeded, four were told, nothing was lost.\n\n## Get started\n\n### For an agent — the point of the thing\n\nPaste this into Claude Code, Cursor, OpenHands, Cline, Windsurf, Zed — anything\nthat speaks MCP:\n\n```\nSet up vnsh workspaces — one link to hand work between people and agents: https://vnsh.dev/llms.txt\n```\n\nIt reads the protocol, installs the MCP server, and writes a standing rule into\nits own instruction file so it keeps using workspaces afterwards. By hand\ninstead:\n\n```bash\nclaude mcp add vnsh -- npx -y vnsh-mcp@1.8.2\n```\n\nThe server exposes `vnsh_artifact_create`, `vnsh_artifact_list`,\n`vnsh_artifact_read`, `vnsh_artifact_update`, `vnsh_workspace_create`, `vnsh_workspace_read`,\n`vnsh_workspace_update`, `vnsh_workspace_history`, `vnsh_workspace_restore`,\n`vnsh_workspace_renew` and `vnsh_workspace_open`, plus\n`vnsh_share`, `vnsh_share_file` and `vnsh_read` for one-shot content.\n\n### From the terminal\n\n```bash\nnpx vnsh # or: npm i -g vnsh\n # or: curl -sL vnsh.dev/i | sh (one-shot links only)\n\nvn ./report.html # create a workspace from a file\ngit diff | vn # or from stdin\nvn read \"\" # read one back — workspace, public, or legacy blob\nvn write \"\" ./new # replace the contents; refuses to clobber\nvn history \"\" # list the latest 20 retained versions\nvn restore \"\" 3 # restore v3 as a new latest version\nvn init . # teach agents in this project to use vnsh\n```\n\n`vn init` adds an idempotent managed section to the project's agent instruction\nfile. It works across agent vendors and records only an anonymous\n\"project initialized\" dimension when that CLI later creates a workspace, so the\nexperiment can be measured without collecting a project name or path.\n\n`--public` publishes it unencrypted (see below). `--blob` explicitly makes a\none-shot link. `--ttl` works for workspaces too, up to 168 hours; subsequent\nwrites preserve that lifetime, and `vn renew` can extend it without an edit.\n\nThe dependency-free shell function from `curl -sL vnsh.dev/i | sh` handles\none-shot links only. Workspaces need HKDF-SHA256 and AES-256-GCM, and the\nopenssl that ships with macOS is LibreSSL, which has neither — it hands `/w/`\nlinks to `npx vnsh` when Node is available and says so plainly when it is not.\n\n### From a browser\n\n — drop a file or paste, and get both links back. Nothing is\nuploaded before it is encrypted.\n\n### From CI\n\n[`upload-to-vnsh`](https://github.com/raullenchai/upload-to-vnsh) uploads build\noutput or failing test logs and prints a link in the job summary.\n\n### From Chrome\n\nThe [extension](extension/) previews vnsh links inline on GitHub, Slack and\nDiscord, and bundles a screenshot, console errors and the page URL into one link\nwith ⌘D.\n\n## The three kinds of link\n\n| Link | Carries | Who can read | Who can write |\n|---|---|---|---|\n| `vnsh.dev/w/{id}#w=` | the root secret | anyone with the link | anyone with the link |\n| `vnsh.dev/w/{id}#r=` | the content key | anyone with the link | **nobody** |\n| `vnshcontent.dev/p/{id}` | nothing | anyone at all | only the author's `#w=` link |\n\nThe view-only tier is not a setting the server enforces — it is arithmetic. The\ncontent key is `HKDF(secret, \"vnsh/enc/v2\")`, a one-way derivation, so its holder\ncan decrypt every version while being unable to recover the secret and therefore\nunable to derive a write token.\n\n**Public workspaces** exist because a person opening a link has a browser doing\nthe decryption for them, and an agent's `fetch` does not. A public workspace is\nstored as written and served as an ordinary document, so anything that speaks\nHTTP can read it with no key and no setup. The trade is stated where you choose\nit: **vnsh can read a public workspace.** It is never the default and never\ninferred, its visibility is fixed at creation, and changing it still requires the\nwrite token.\n\nThey are served from **`vnshcontent.dev`**, a separate registrable domain, and\nthat is not cosmetic. A public document is written by a stranger and rendered as\na top-level page, while reputation systems — Safe Browsing, mail gateways,\ncorporate proxies — list a domain rather than a path. One abusive page on\n`vnsh.dev` would take the API, the site and every installed CLI, MCP server and\nextension down with it. A subdomain would not help; the unit is the registrable\ndomain. Sandboxing is a separate matter and already handled: a public document\nis served with a `sandbox` CSP directive, so it loads into an opaque origin with\nno cookies, no storage, no network and no access to any other page. `/w/` links\nstay on `vnsh.dev` because the key in the fragment is a real gate — the server\nhas never seen their plaintext and neither can a crawler.\n\nDon't assemble a public URL yourself. Creating one returns the exact link in the\nresponse's `url` field, which is also what keeps a self-hosted single-domain\ninstance working.\n\n## How it works\n\n```\nyou ──encrypt──▶ [ vnsh: ciphertext, no key ] ──decrypt──▶ agent / person\n │\n deleted 24h after the last write\n```\n\n**Key schedule**\n\n```\nS = random(32) root secret, lives only in the fragment\nK = HKDF-SHA256(S, \"vnsh/enc/v2\") content key — AES-256-GCM\nW = HKDF-SHA256(S, \"vnsh/write/v2\") write token, sent as 64 hex chars\nH = SHA-256(W) the only derived value the server stores\n```\n\nWorkspaces use **AES-256-GCM**, not the AES-256-CBC of one-shot blobs, because\nmutable content needs integrity: without an authentication tag, anyone able to\nrewrite storage — the host included — could flip ciphertext bits undetectably,\nwhich hollows out the whole guarantee. Nonces are random per write and prepended,\nnever derived from a version number.\n\nThe viewer renders HTML and markdown in a frame with `sandbox=\"allow-scripts\"`\nand deliberately no `allow-same-origin`, so content runs in an opaque origin and\ncannot read the key out of `location.hash`; an injected `default-src 'none'`\nremoves its network access.\n\nThe whole protocol is specified in [`/llms.txt`](https://vnsh.dev/llms.txt),\ncreation included, so you can implement it in any language with a crypto library\nand run no vnsh code at all. Someone did, in about 200 lines.\n\n## API\n\n| Endpoint | Purpose |\n|---|---|\n| `POST /api/workspace` | Create. Requires `X-Vnsh-Write-Hash`; `X-Vnsh-Public: 1` to publish. Returns `url` when public. |\n| `GET /api/workspace/:id` | Read ciphertext. `ETag` is the version. |\n| `PUT /api/workspace/:id` | Replace. Requires `X-Vnsh-Write` and `If-Match`. |\n| `GET /w/:id` | The viewer. Decrypts client-side, renders sandboxed. |\n| `GET /p/:id` | A public workspace, as a plain document — on `vnshcontent.dev`. |\n| `POST /api/drop` | One-shot blob (v1). `?ttl=` and `?price=`. |\n| `GET /api/blob/:id` | Read a one-shot blob. |\n| `GET /llms.txt` | The protocol, written for agents. |\n\nWrites answer `428` without `If-Match`, `412` on a stale version, and `403` on a\nbad write token. Full reference in [`docs/api.md`](docs/api.md).\n\n## Security model\n\n### Accounts and permanent artifacts\n\nAnonymous sharing remains account-free and temporary. Sign in at\n`https://account.vnsh.dev` with a magic link to keep newly created workspaces\nand `/artifact/` pages until you delete them. Browser creates use the signed-in\nsession automatically. For the CLI, run `vn login` and approve the device in\nyour browser. MCP and CI can use an account token in `VNSH_TOKEN`; content is\nstill encrypted locally for capability-link workspaces, and the account database\nstores only their ownership metadata, not keys or plaintext.\nDuring the free preview, each account can keep 100 documents and 1 GB total,\nincluding retained versions.\nKeep the returned link: its fragment is the only copy of the decryption/editing\nsecret, so the account can manage retention and deletion but cannot recover a\nlost key.\n\nPhase 1 account Artifacts add a separate collaboration mode: authenticated\nhumans and Agent tokens can discover and version private Artifact content\nwithout carrying a fragment key. That convenience has a different security\nboundary—vnsh can technically read account Artifact content. It is never\nsilently substituted for an anonymous encrypted workspace, and only a human\nmay approve or publish by default.\n\n```sh\nvn login\nvn artifact create report.md --title \"Release report\" --type report\nvn artifact list --query release --status draft\nvn artifact read \nvn artifact update report.md --base-version 1 --change-summary \"Verified production\"\n```\n\nAdd `--json` to any Artifact command when another program or Agent will consume\nthe result.\n\n**What holds.** vnsh cannot read encrypted content, cannot write to it, and\ncannot recover a write token from anything it stores. Rendered content runs with\nno same-origin access and no network, so a hostile document can neither reach the\nkey nor send anything anywhere.\n\n**What does not.**\n\n- **Handing someone a link hands them the key**, including that agent's model\n provider. The 24-hour clock is what bounds this, not the encryption — and each\n write restarts it, so a workspace edited daily stays alive.\n- **The boundary is the client, not the transport.** Whatever encrypts holds your\n plaintext first, and the MCP server and CLI both do. `npx -y` refetches the\n latest published version on every start; pin it (`vnsh-mcp@1.8.2`), install it\n globally once, or build from source if you review what you run.\n- **A public workspace is readable by vnsh**, by design. That is the tier.\n- **Metadata is not private.** Times, sizes and addresses exist for any hosted\n service. Only the content does not.\n\n## Self-hosting\n\nCloudflare Workers plus an R2 bucket. No database, no KV.\n\n```bash\ngit clone https://github.com/raullenchai/vnsh.git\ncd vnsh/worker && npm install\nwrangler r2 bucket create vnsh-store\nwrangler deploy\n```\n\n`wrangler.toml` binds R2, two native rate limiters and an Analytics Engine\ndataset. Earlier versions used a KV namespace for metadata and counters; it was\nremoved after the free-tier write cap took the whole site down, and nothing needs\nit now — if you are following an older guide that tells you to create one, you do\nnot. See [`docs/self-hosting.md`](docs/self-hosting.md).\n\n## Repository\n\n| Path | What it is |\n|---|---|\n| `worker/` | Cloudflare Worker: API, viewer, homepage, `llms.txt` |\n| `mcp/` | `vnsh-mcp` — the MCP server agents use |\n| `cli/npm/` | `vnsh` — the `vn` command |\n| `cli/` | `install.sh` and the dependency-free shell function |\n| `extension/` | Chrome extension |\n| `docs/` | Architecture, API, CLI, MCP, operations, self-hosting |\n| `docs/plans/` | Design documents, including the v2 workspace plan |\n\n```bash\nnpm test # every package\ncd worker && npm run dev # local worker\n```\n\nFour packages carry their own copy of the key schedule, because they ship\nindependently. Each is pinned to the same test vectors: a link made by one that\nwill not open in another reads as corruption rather than version skew, so the\nfailure would be silent. If you change a derivation, those tests are what stops\nthat happening quietly.\n\n## Contributing\n\nIssues and pull requests welcome, including the ones that tell us we are wrong —\nthe most useful contribution so far was someone reimplementing the protocol from\n`llms.txt` and reporting everything the document had failed to say.\n\nStart with [CONTRIBUTING.md](CONTRIBUTING.md). It covers the two traps in this\ncodebase that catch everyone: the worker's client-side code lives inside a\ntemplate literal, so backslashes must be doubled and a stray backtick ends the\nstring a hundred lines from where the compiler complains.\n\nFound a security issue? Please do not open a public issue —\n[SECURITY.md](SECURITY.md) has the private form, and lists what is claimed and\nwhat is deliberately not.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n

\n \n vnsh.dev ·\n the protocol ·\n docs ·\n why it is built this way\n \n

\n", "bytes": 15170, "sha": "61d695df0d056b13480806bd3590f47ff8c87d805ab71953c9cec3d7c6e6a358", "repo_slug": "raullenchai/vnsh", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_raullenchai_vnsh_b4e30182/readme" }