vnsh-mcp

<p align="center"> <img src="https://vnsh.dev/logo.svg" alt="vnsh logo" width="120" /> </p>

<h1 align="center">vnsh</h1>

<p align="center"> <strong>The Ephemeral Dropbox for AI</strong> </p>

<p align="center"> <a href="https://github.com/raullenchai/vnsh/actions"><img src="https://img.shields.io/github/actions/workflow/status/raullenchai/vnsh/test.yml?branch=main&style=flat-square" alt="Build Status"></a> <a href="https://www.npmjs.com/package/vnsh"><img src="https://img.shields.io/npm/v/vnsh?style=flat-square&label=vnsh" alt="npm vnsh"></a> <a href="https://www.npmjs.com/package/vnsh-mcp"><img src="https://img.shields.io/npm/v/vnsh-mcp?style=flat-square&label=vnsh-mcp" alt="npm vnsh-mcp"></a> <a href="https://github.com/raullenchai/upload-to-vnsh"><img src="https://img.shields.io/badge/GitHub%20Action-upload--to--vnsh-green?style=flat-square&logo=githubactions" alt="GitHub Action"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="License"></a> </p>

<p align="center"> <a href="https://vnsh.dev">Website</a> • <a href="#quick-start">Quick Start</a> • <a href="#how-it-works">How It Works</a> • <a href="#self-hosting">Self-Hosting</a> • <a href="#api-reference">API</a> </p>

---

What is vnsh?

<p align="center"> <img src="https://vhs.charm.sh/vhs-3Ex3csS9i3iMvjOVO7WJc5.gif" alt="vnsh demo" width="800" /> </p>

Stop pasting walls of text into Claude. Pipe your logs, diffs, and images into a secure, host-blind URL. The server sees nothing. The data vaporizes in 24 hours.

# Pipe anything to vnsh, get a secure link
git diff | vn
# https://vnsh.dev/v/aBcDeFgHiJkL#R_sI4DHZ_6jNq6yqt2ORRDe9QZ5xQB6hIRLWHVFa8v8

Handles any context your AI needs:

• 🖼️ Screenshots — UI bugs, error dialogs, terminal output
• 📜 Logs — 5000+ lines of server errors (too long for copy-paste)
• 🔄 Git Diffs — Complex PR reviews, multi-file changes
• 📦 Binaries — PDFs, CSVs, config files, database dumps
• 🔧 Debug Context — Stack traces, environment dumps, crash reports

Philosophy

"Built for the ephemeral nature of AI workflows. Once your session is done, the data should be too."

Unlike Dropbox or pastebins, vnsh implements a Host-Blind Architecture with automatic vaporization:

Layer	What Happens
Encryption	AES-256-CBC encryption happens entirely on your device
Transport	Decryption keys travel only in the URL fragment (#secret) — never sent to servers
Storage	Server stores encrypted binary blobs — host-blind, no access to contents
Vaporization	Data vaporizes after 24 hours. No history. No leaks.

Quick Start

Option 1: Web Upload

Visit vnsh.dev, drag & drop a file, or paste text. Get an encrypted link instantly.

Option 2: CLI Installation

Zero-install (just run it):

echo "hello" | npx vnsh

NPM (global install):

npm install -g vnsh

Shell script (cross-platform: macOS, Linux, WSL, Git Bash):

curl -sL https://vnsh.dev/i | sh

CLI Usage

# Upload a file
vn secrets.env

# Pipe from stdin
cat crash.log | vn
docker logs app | vn
git diff HEAD~5 | vn

# Read/decrypt a URL
vn read "https://vnsh.dev/v/aBcDeFgHiJkL#R_sI4DHZ..."

# Custom expiry (1-168 hours)
vn --ttl 1 temp-file.txt   # expires in 1 hour

# Show version and help
vn --version
vn --help

Option 3: Claude Code (MCP Integration)

Native to Claude Code. Unlike Dropbox, vnsh has a first-party MCP server. Claude can "see" inside your encrypted links without leaving the terminal.

Create .mcp.json in your project root:

{
  "mcpServers": {
    "vnsh": {
      "command": "npx",
      "args": ["-y", "vnsh-mcp"]
    }
  }
}

Restart Claude Code after adding the config. Now Claude can:

• Read vnsh links automatically when you paste them
• Share large text outputs via vnsh_share tool
• Share files (images, PDFs, binaries) via vnsh_share_file tool

Option 4: Zero-Install (Remote Servers)

No installation needed. Pipe anything from any server with just curl and openssl:

# One-liner: encrypt and upload from any machine
cat error.log | bash <(curl -sL vnsh.dev/pipe)
# https://vnsh.dev/v/aBcDeFgHiJkL#R_sI4DHZ_6jNq6yqt2ORRDe9...

# Works with any command
kubectl logs pod/crash | bash <(curl -sL vnsh.dev/pipe)
docker logs app 2>&1 | bash <(curl -sL vnsh.dev/pipe)
journalctl -u nginx --since "1 hour ago" | bash <(curl -sL vnsh.dev/pipe)

# Custom TTL (hours)
cat secrets.env | bash <(curl -sL vnsh.dev/pipe?ttl=1)

Perfect for SSH sessions, CI runners, Docker containers — anywhere you can't install tools.

Option 5: Chrome Extension

One-click encrypted debug bundles for AI. Share text, screenshots, and console errors directly from your browser.

• Right-click any selected text → Share via vnsh
• Cmd+Shift+D → AI Debug Bundle (screenshot + console errors + selected text + URL, all encrypted)
• Hover over vnsh links on any page → see decrypted preview tooltip

Build from source or install from the Chrome Web Store (pending review):

cd extension && npm install && npm run build
# Load dist/ as unpacked extension in chrome://extensions/

See extension/README.md for full documentation.

Option 6: GitHub Action (CI/CD)

Debug CI failures with Claude in one click. When your CI fails, automatically upload logs and post a secure link to your PR.

- name: Debug with vnsh
  if: failure()
  uses: raullenchai/upload-to-vnsh@v1
  with:
    file: test.log
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

The action will post a comment to your PR:

🔍 Debug with Claude

CI logs uploaded securely. View Logs | Paste link to Claude for instant analysis

See upload-to-vnsh for full documentation.

How It Works

┌──────────────────────────────────────────────────────────────────────────┐
│                              YOUR DEVICE                                  │
│  ┌─────────┐    ┌──────────────┐    ┌─────────────────────────────────┐  │
│  │  Data   │───▶│ AES-256-CBC  │───▶│  Encrypted Blob + URL Fragment  │  │
│  └─────────┘    │  Encryption  │    │  https://vnsh.dev/v/id#k=...    │  │
│                 └──────────────┘    └─────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────────┘
                                           │
                           Only encrypted blob sent to server
                           (key stays in URL fragment, never transmitted)
                                           ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                           VNSH SERVER (BLIND)                             │
│                                                                           │
│   Receives: [encrypted binary blob]                                       │
│   Stores:   [encrypted binary blob]                                       │
│   Knows:    upload time, size, expiry                                     │
│   Cannot:   decrypt, identify content type, read keys                     │
│                                                                           │
└──────────────────────────────────────────────────────────────────────────┘

URL Structure (v2 — compact format)

https://vnsh.dev/v/aBcDeFgHiJkL#R_sI4DHZ_6jNq6yqt2ORRDe9QZ5xQB6hIRLWHVFa8v8jYCFqgQIbsRJrtJze_nL5
                  └────────────┘└────────────────────────────────────────────────────────────────────┘
                  12-char ID     64-char base64url secret (key+iv, never sent to server)

The v2 format reduces URL length by ~40% (from ~160 to ~95 characters). Legacy v1 URLs (#k=...&iv=...) are still fully supported.

Self-Hosting

vnsh runs on Cloudflare Workers with R2 storage. Deploy your own instance:

Prerequisites

• Cloudflare account with Workers & R2 enabled
• Wrangler CLI

Deploy

# Clone the repository
git clone https://github.com/raullenchai/vnsh.git
cd vnsh/worker

# Install dependencies
npm install

# Create R2 bucket
wrangler r2 bucket create vnsh-store

# Deploy
wrangler deploy

Configuration

Edit wrangler.toml to customize:

name = "vnsh"

[[r2_buckets]]
binding = "VNSH_STORE"
bucket_name = "vnsh-store"  # Your R2 bucket name

[[kv_namespaces]]
binding = "VNSH_META"
id = "your-kv-namespace-id"  # Create with: wrangler kv namespace create VNSH_META

API Reference

POST /api/drop

Upload an encrypted blob.

curl -X POST https://vnsh.dev/api/drop \
  -H "Content-Type: application/octet-stream" \
  --data-binary @encrypted.bin

Query Parameters:

Parameter	Type	Description
ttl	number	Time-to-live in hours (1-168, default: 24)
price	number	Payment required to access (x402 protocol)

Response:

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "expires": "2025-01-25T00:00:00.000Z"
}

GET /api/blob/:id

Download an encrypted blob.

curl https://vnsh.dev/api/blob/a1b2c3d4-5678-90ab-cdef-1234567890ab

Response Codes:

Code	Description
200	Success — returns encrypted blob
402	Payment required
404	Not found
410	Expired

GET /v/:id

Web viewer (serves HTML directly to preserve URL fragment with encryption keys).

GET /i

CLI installation script.

GET /pipe

Zero-install pipe upload script. Returns a shell script that encrypts stdin and uploads it.

cat file.log | bash <(curl -sL vnsh.dev/pipe)

Query Parameters:

Parameter	Type	Description
ttl	number	Time-to-live in hours (1-168, default: 24)

GET /claude

Claude Code MCP integration installer script.

Security Model

What vnsh Protects Against

✅ Server Compromise — Even with full server access, attackers cannot decrypt blobs ✅ Database Leaks — Stored data is indistinguishable from random noise ✅ Traffic Analysis — No content-type information stored ✅ Subpoenas — Server operator cannot produce plaintext (doesn't have keys)

What vnsh Does NOT Protect Against

❌ URL Sharing — Anyone with the full URL (including #fragment) can decrypt ❌ Client Compromise — Malware on your device can intercept before encryption ❌ MITM on Upload Page — An attacker serving malicious JavaScript could intercept

Recommendations

• Use vnsh over HTTPS only
• Don't share full URLs in public channels (Slack, Discord, Twitter)
• For maximum security, self-host the worker

Project Structure

vnsh/
├── worker/          # Cloudflare Worker (storage API + web viewer)
│   ├── src/
│   │   └── index.ts # Main worker code
│   └── test/
│       └── api.test.ts
├── mcp/             # MCP Server (Claude Code integration)
│   ├── src/
│   │   ├── index.ts # MCP tool handlers
│   │   └── crypto.ts # Encryption utilities
│   └── package.json
├── extension/       # Chrome Extension (AI debug sharing)
│   ├── src/
│   │   ├── lib/     # Shared crypto, API, storage
│   │   ├── background/ # Service worker
│   │   ├── content/    # Link detector + tooltip
│   │   └── popup/      # Extension popup UI
│   └── tests/
├── cli/
│   ├── vn           # Bash CLI script
│   ├── npm/         # NPM package (vnsh)
│   │   ├── src/
│   │   │   ├── cli.ts
│   │   │   └── crypto.ts
│   │   └── package.json
│   └── install.sh   # Shell installer
├── homebrew-tap/    # Homebrew formula
│   └── Formula/
│       └── vnsh.rb
└── docs/            # Documentation

Packages

Package	Description	Install
vnsh	CLI tool	npx vnsh or npm i -g vnsh
vnsh-mcp	MCP server for Claude	npx vnsh-mcp
vnsh extension	Chrome Extension	Chrome Web Store
upload-to-vnsh	GitHub Action for CI/CD	uses: raullenchai/upload-to-vnsh@v1
homebrew-vnsh	Homebrew tap	brew install raullenchai/vnsh/vnsh

Development

# Clone
git clone https://github.com/raullenchai/vnsh.git
cd vnsh

# Install dependencies
npm install
cd worker && npm install
cd ../mcp && npm install

# Run tests
npm test                          # Worker + MCP tests
cd extension && npm test          # Extension tests (48 tests, 93%+ coverage)
cd extension && npm run test:cov  # Extension tests with coverage

# Start local worker
cd worker && npm run dev

# Build MCP server
cd mcp && npm run build

# Build extension
cd extension && npm install && npm run build
# Load extension/dist/ as unpacked in chrome://extensions/

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting a PR.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run tests (npm test)
4. Commit changes (git commit -m 'Add amazing feature')
5. Push to branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

MIT License — see LICENSE for details.

---

<p align="center"> _{The Ephemeral Dropbox for AI. Your context. Your keys. Then it's gone.} </p>