# VirtualDrive Cloud

> Object storage for developers and AI agents. Add secure, scalable file storage
> to any app with a scoped API key — REST, SDKs (JS + Python), a CLI, and a
> native MCP server. Files are private by default and served via short-lived
> signed URLs.

## Base URL
https://rmfxldmlnbkljpoofeaj.supabase.co/functions/v1

## Authentication
Send your project API key as a Bearer token: `Authorization: Bearer vdk_live_...`
Keys are scoped to one project with permissions: files:read, files:write, files:delete.
Keys are shown once at creation; store them as a secret.

## REST data plane — POST /dev-files  { action, ... }
- presign-upload { name, contentType, size? } -> { fileId, uploadUrl, key } ; then HTTP PUT the bytes to uploadUrl (no auth header — the URL is presigned), then:
- confirm { fileId, size? } -> marks the file stored
- list { prefix?, limit? } -> { files: [{ id, name, size, content_type, created_at }] }
- signed-url { fileId, expiresIn? } -> { url } (short-lived download URL)
- delete { fileId } -> { ok: true }

Status codes: 401 invalid key · 403 missing scope · 404 not found · 503 service paused.

## MCP server (for AI agents)
Endpoint: https://rmfxldmlnbkljpoofeaj.supabase.co/functions/v1/dev-mcp
JSON-RPC 2.0. Auth: Authorization: Bearer vdk_live_...
Methods: initialize, tools/list, tools/call.
Tools: list_files, write_file{name,content,contentType?}, read_file{fileId}, delete_file{fileId}.

## SDKs
- JavaScript/TypeScript: `npm i @virtualdrive/cloud`
    import { VirtualDrive } from "@virtualdrive/cloud";
    const vd = new VirtualDrive(process.env.VD_API_KEY);
    const file = await vd.files.upload({ name: "hi.txt", data: "hello" });
- Python: `pip install virtualdrive`
    from virtualdrive import VirtualDrive
    vd = VirtualDrive(api_key=os.environ["VD_API_KEY"])
    f = vd.files.upload(name="hi.txt", data="hello")
- CLI: `vd files upload ./file.pdf`

## Notes
- Files are never public; access is via signed, expiring URLs only.
- Encryption at rest (AES-256) and TLS in transit.
- Usage is metered per project (stored bytes + requests). Free tier at launch.
- Docs: https://virtualdrive.us/developers/docs/
- Status: early access (APIs may change before GA).