Content
<div align="center">
<img src="web/public/assets/logo.png" alt="Disk" width="96" height="96" />
# Disk
**Personal cloud storage on Cloudflare — for you and your agents.**
Any file, any size · scoped API keys · full audit trail · agent-ready
(REST + OpenAPI + MCP)
[**disk.zaynjarvis.com**](https://disk.zaynjarvis.com) · built on Cloudflare
Workers · R2 · D1
</div>
---
<div align="center">
<img src="docs/screenshots/files.png" alt="Disk file browser" width="820" />
</div>
## What it is
Disk is one Cloudflare Worker in front of **R2** (file bytes), **D1** (keys,
shares, audit), and a **React** SPA. It's a Dropbox-lite you own outright —
and every capability is equally available over a clean API so your agents can
use it as scratch space, artifact storage, or a shared drive.
## Features
- 🔑 **API-key auth with roles** — a `ROOT_KEY` env secret, revocable
root-equivalent **admin** keys, and scoped **user** keys (path prefix,
read-only/read-write, per-file upload cap, expiry).
- 🗂️ **Virtual root per key** — a scoped key sees its prefix *as* the root and
never perceives or escapes it. Hand an agent a key scoped to `agents/zouk/`
and, to that agent, its world simply starts at `/`.
- 📤 **Any file, any size** — drag-and-drop and folder uploads, multipart for
multi-GB files, Range downloads, previews (image / video / audio / PDF /
markdown / code).
- 👀 **Four ways to browse** — List, Grid, **Tree**, and a Finder-style
**Column** view that previews the selected file in a pane on the right,
making full use of wide screens.
- 🔗 **Shares** — revocable, expiring public links (`/s/<token>`), download-counted.
- 📜 **Full audit** — every request logged (actor, action, path, bytes, status,
IP, UA); filterable UI + CSV export for admins.
- 🤖 **Agent-ready** — REST at `/api/v1`, OpenAPI 3.1 at `/openapi.json`, an
agent guide at `/llms.txt`, and an **MCP server** at `POST /mcp` — including
admin tools so an agent can manage keys itself.
## Screenshots
| Sign in | Preview anything |
|---|---|
| <img src="docs/screenshots/login.png" width="400" /> | <img src="docs/screenshots/preview.png" width="400" /> |
| API keys — roles, scopes, upload caps | Storage usage |
|---|---|
| <img src="docs/screenshots/keys.png" width="400" /> | <img src="docs/screenshots/usage.png" width="400" /> |
**Column view** — Finder-style Miller columns with a live preview pane on the
right; and a **Tree** view for a bird's-eye look. Different views for different
audiences.
| Column view + preview pane | Tree view |
|---|---|
| <img src="docs/screenshots/column.png" width="400" /> | <img src="docs/screenshots/tree.png" width="400" /> |
**Virtual root** — the same disk, seen through a key scoped to `agents/zouk/`.
No prefix, no other folders, no admin views: its scope *is* the root.
<div align="center">
<img src="docs/screenshots/scoped.png" alt="Scoped key virtual root" width="700" />
</div>
## How to use it
### As a person
1. Open [disk.zaynjarvis.com](https://disk.zaynjarvis.com).
2. Paste an API key (your `ROOT_KEY`, or any key you minted) and sign in.
3. Drag files in, preview them, share links, and — as root/admin — mint keys
and read the audit log.
### As an agent
Mint a key for the agent in the **Keys** tab (or via the API), then point it at
Disk. Give it a **scoped** key so it can only touch its own corner:
```sh
# (admin) mint a scoped read-write key with a 10 MB per-file cap
curl -s -X POST https://disk.zaynjarvis.com/api/v1/keys \
-H "Authorization: Bearer $ROOT_KEY" -H 'Content-Type: application/json' \
-d '{"name":"zouk-agent","prefix":"agents/zouk/","permission":"rw","maxUploadBytes":10485760}'
# → returns {"key":"dk_…"} (shown once)
```
The agent then speaks **scope-relative** paths — it never sees `agents/zouk/`:
```sh
export DISK_KEY=dk_...
# upload (stored at agents/zouk/notes/todo.md, but the agent just says "notes/todo.md")
curl -s -X PUT "https://disk.zaynjarvis.com/api/v1/files/blob?path=notes/todo.md" \
-H "Authorization: Bearer $DISK_KEY" --data-binary @todo.md
# list its root
curl -s "https://disk.zaynjarvis.com/api/v1/files" -H "Authorization: Bearer $DISK_KEY"
# share a file
curl -s -X POST https://disk.zaynjarvis.com/api/v1/shares \
-H "Authorization: Bearer $DISK_KEY" -H 'Content-Type: application/json' \
-d '{"path":"notes/todo.md","ttlSeconds":3600}'
```
Full curl reference for every operation: **[/llms.txt](https://disk.zaynjarvis.com/llms.txt)**.
### Over MCP
Connect any MCP client (Claude Code, Claude Desktop, Cursor, …). The agent gets
native tools — `disk_list`, `disk_read`, `disk_write`, `disk_delete`,
`disk_move`, `disk_share`, and (for admin keys) `disk_key_create` /
`disk_key_list` / `disk_key_revoke`:
```json
{ "mcpServers": { "disk": {
"type": "http",
"url": "https://disk.zaynjarvis.com/mcp",
"headers": { "Authorization": "Bearer dk_..." }
} } }
```
Hand an agent an **admin** key and it can administer the whole disk — including
minting and revoking other keys — entirely through MCP.
## Stack
Hono on Cloudflare Workers · R2 · D1 · React 19 + Vite + Tailwind v4 · vitest
(`@cloudflare/vitest-pool-workers`). One `wrangler deploy` ships the API, the
MCP server, and the SPA together.
## Contributing & deploying
- **[DEV.md](DEV.md)** — local setup, the contract-first rule, security-core
invariants, recipes, and gotchas.
- **[DEPLOY.md](DEPLOY.md)** — architecture, provisioned resources, redeploy,
migrations, disaster-recovery bootstrap.
- **[API.md](API.md)** — the binding API contract.
Screenshots above are generated with `node scripts/screenshots.mjs` against a
local dev server.
