# Dropzone

> End-to-end encrypted, single-use links for files and text. Each drop is encrypted with AES-256-GCM, can be opened exactly once, and is permanently deleted the moment it is opened (or after 90 days). Use it to hand secrets, API keys, .env files and sensitive documents to a human or another agent instead of pasting them in plaintext.

No account or API key is required. All endpoints support CORS. Source code: https://github.com/slugiscool99/dropzone

Share links look like `https://dropzone.sh/d/<id>#<key>`. The key is the part after `#`; keep the whole link intact.

## Important rules for agents

- A drop link works ONCE. Opening it (Reveal in a browser, the CLI, /api/retrieve, or the MCP open_drop tool) permanently deletes the data.
- If you create a link for someone else, do not open it yourself, or the recipient will get nothing.
- Only open a link when you actually need its contents, and only once. Save the contents if you will need them again.
- Loading the HTML page at /d/... never consumes the drop (a human has to click "Reveal"); it contains these same instructions.
- Link previews are safe: chat unfurlers, crawlers, email scanners and HEAD requests never consume a drop. Share `url`, not `retrieveUrl`.
- If you have a shell, prefer the CLI: it encrypts and decrypts locally, so Dropzone never sees the data or the key.

## Choose an integration

| Option | Where encryption happens | Max size |
| --- | --- | --- |
| CLI (`dropzone.mjs`) | On your machine (end-to-end) | ~4MB |
| Web app | In the browser (end-to-end) | 100MB |
| Raw API (`/api/drops`) with your own encryption | On your machine (end-to-end) | ~4MB |
| Hosted MCP server | On the Dropzone server (key never stored) | ~3MB |
| Plaintext HTTP API (`/api/upload`, `/api/retrieve`) | On the Dropzone server (key never stored) | ~4MB |

## CLI (end-to-end encrypted)

A single file with no dependencies (Node 20+). Read it before running it if you like: https://dropzone.sh/dropzone.mjs

```sh
curl -fsSO https://dropzone.sh/dropzone.mjs
node dropzone.mjs send .env                  # file -> prints a single-use link
echo "hunter2" | node dropzone.mjs send      # stdin -> text drop
node dropzone.mjs send --text "sk-live-123"
node dropzone.mjs open "$LINK"               # text to stdout, files saved by name (-o path to choose)
```

## MCP server (server-assisted)

Streamable HTTP endpoint: https://dropzone.sh/api/mcp

- `create_drop` { text } or { content_base64, filename } -> single-use link
- `open_drop` { url } -> decrypted contents (destructive)

Claude Code: `claude mcp add --transport http dropzone https://dropzone.sh/api/mcp`

Other clients: { "mcpServers": { "dropzone": { "type": "http", "url": "https://dropzone.sh/api/mcp" } } }

## HTTP API

OpenAPI spec: https://dropzone.sh/openapi.json

### Create a drop from plaintext (server-assisted): POST https://dropzone.sh/api/upload

```sh
curl -s https://dropzone.sh/api/upload -H 'Content-Type: application/json' -d '{"text":"sk-live-123"}'
echo "hunter2" | curl -s https://dropzone.sh/api/upload --data-binary @-
curl -s https://dropzone.sh/api/upload -F file=@.env
curl -s "https://dropzone.sh/api/upload?filename=report.pdf" --data-binary @report.pdf -H 'Content-Type: application/octet-stream'
```

JSON body alternatives: {"text": "..."} or {"content_base64": "...", "filename": "photo.png"}.

Response (201):

```json
{
  "url": "https://dropzone.sh/d/<id>#<key>",
  "retrieveUrl": "https://dropzone.sh/api/retrieve?id=<id>&key=<key>",
  "kind": "text",
  "filename": null,
  "size": 7,
  "singleUse": true
}
```

### Open a drop (server-assisted): GET https://dropzone.sh/api/retrieve?url=<url-encoded share link>

Also accepts `?id=...&key=...`, or POST with JSON {"url": "..."}. URL-encode the link so the `#key` part is sent. Prefer POST: keys in a GET query string can end up in request logs.

Max ~4MB (the response is not streamed). Larger drops are refused without being opened; open them in a browser or with the CLI.

- Default: raw decrypted bytes, with Content-Type, Content-Disposition and X-Dropzone-Kind / X-Dropzone-Filename headers.
- `&format=json`: {"kind","filename","mimeType","size","text"} for text, or "content_base64" for binary files.

```sh
curl -s https://dropzone.sh/api/retrieve -H 'Content-Type: application/json' -d "{\"url\": \"$LINK\"}"
```

### End-to-end API (bring your own encryption)

- `POST https://dropzone.sh/api/drops` with a v2 ciphertext body (application/octet-stream, max 4MB) -> {"id","url"}. Append `#<key>` to `url` yourself.
- `POST https://dropzone.sh/api/drops/<id>` -> the ciphertext, exactly once (GET never consumes). Decrypt locally.
- Format: `[0x02][12-byte IV][AES-256-GCM ciphertext+tag]` with the version byte as AAD; plaintext is `[uint32 BE header length][header JSON {kind,name?,type?}][content]`; key is 32 random bytes, base64url, in the URL fragment. Reference implementation: https://dropzone.sh/dropzone.mjs

Errors are JSON: {"error": "...", "code": "not_found" | "invalid_link" | "invalid_key" | "too_large" | "empty" | ...}.
`not_found` (404) means the drop never existed or was already opened. With end-to-end links the server can't check keys, so a link with a wrong key is still used up when opened.

## Security model

- Web app and CLI: data, filenames and types are encrypted on the sender's device with a random 256-bit key. The key exists only in the link's #fragment, which is never sent to Dropzone. Dropzone stores only ciphertext, in private storage. (Legacy /decrypt drops from before end-to-end encryption are public blobs with plaintext filenames; they expire within 90 days.)
- Plaintext API and hosted MCP: the server encrypts or decrypts in memory for that request and never stores plaintext or keys.
- Single use: opening a drop takes a create-only lock, so two simultaneous opens cannot both succeed. The ciphertext is deleted right after.
- Unopened drops are deleted after 90 days.
- Details and threat model: https://github.com/slugiscool99/dropzone/blob/main/SECURITY.md

## Guides for agents

- [Dropzone for AI agents](https://dropzone.sh/agents): setup for Claude Code, Cursor, VS Code and other MCP clients
- [Dropzone is now agent-native](https://dropzone.sh/blog/dropzone-for-ai-agents/md): MCP server, API and llms.txt
- [How AI agents should handle secrets](https://dropzone.sh/blog/how-ai-agents-should-handle-secrets/md): rules for keeping secrets out of transcripts and logs
- [Give your coding agent a .env file](https://dropzone.sh/blog/give-your-coding-agent-a-env-file/md): step-by-step tutorial
- [Agent-to-agent secret handoff](https://dropzone.sh/blog/agent-to-agent-secret-handoff/md): passing credentials between agents

## Suggested project instructions (AGENTS.md / CLAUDE.md)

```md
## Secrets
- Never paste secrets, API keys, or .env contents into chat or logs.
- To share a secret with a human or another agent, create a single-use
  Dropzone link (`node dropzone.mjs send`, MCP tool `create_drop`,
  or see https://dropzone.sh/llms.txt).
- Only open a Dropzone link when its contents are meant for you, and only once.
```

## Optional

- [Full documentation including all blog posts](https://dropzone.sh/llms-full.txt)

## Links

- [Home](https://dropzone.sh/)
- [FAQ](https://dropzone.sh/faq)
- [Blog](https://dropzone.sh/blog)
- [Privacy policy](https://dropzone.sh/legal/privacy)
