Built for the age of AI agents

copy# Storage Architecture Purpose-built for AI agents and humans to collaborate on files. Storage is an edge-first file storage platform. Every design decision, from content addressing to event sourcing to the dual identity model, serves both human users and AI agents through one unified API. ## System Overview ### Layers ## Meta Pane The Meta Pane stores all structured data: file entries, events, sessions, blob references, and transaction counters. It separates file identity from file content, similar to how UNIX inodes separate a filename from disk blocks. ### Data Model ### Why This Enables Fast Operations - Move / Rename: Update the path column. Zero blob copies. O(1). - Deduplication: Same addr means same blob. Upload once, reference many times. - Delete: Decrement ref_count. Only delete the blob when it reaches zero. - Integrity: The hash IS the address. Corruption is self-evident. ## Request Lifecycle ### Upload Flow - Client-side SHA-256 enables instant deduplication before upload - File bytes upload directly to the content-addressed blob location - On confirm, edge verifies via HEAD (no data pull), then records metadata - Zero file data flows through the edge worker ### Multipart Upload - Up to 10,000 parts per upload - Parts upload in parallel directly to object storage - Same zero-proxy guarantee as single uploads - Same client-side SHA-256 dedup check ### Download Flow - Zero bandwidth through API server - No egress fees from Object Storage ### Range Read Downloads redirect to presigned object storage URLs, which natively support HTTP Range headers. Partial downloads never touch the edge worker. - Resume interrupted downloads from last byte - Read specific byte ranges without downloading the full file - All byte serving happens at the storage layer ## Content Addressing Every file is stored by the SHA-256 hash of its content: ### Properties - Automatic deduplication: same content = same blob, always - Free integrity verification: the hash IS the identifier - Zero-cost rename and move: only the Meta Pane path changes - Collision risk ~2^-128: effectively zero Upload the same file twice, one blob stored. Rename a file, zero bytes copied. ## Event Architecture Every mutation in the system produces an immutable event. This is not just logging. It is the primary source of truth for what happened, when, and by whom. ### Event Log ### Properties - Append-only: events are never updated or deleted (until GC compaction) - Per-actor isolation: each actor has its own transaction counter - Dense sequence: tx numbers have no gaps, ordered by insertion time - Monotonic: tx counter never resets ### Smart Versioning Every put to the same path creates a new event with a new addr. The previous version is still in the event log. You can reconstruct the full history of any file by reading events for that path. ### Replayable Given the event log, you can reconstruct the complete state of any actor's storage at any point in time. Start from tx 0, apply events in order, and you get the exact file tree. ### Auditable Every event records who did what, when. No action goes untracked. For AI agents operating autonomously, this provides complete accountability. ### Realtime Change Tracking Agents can poll for events since their last known tx number. No need to list all files and diff. Just ask "what changed since tx 42?" and get exactly the new events. ### Why This Matters for AI Agents - Incremental sync without full directory scans - No race conditions between concurrent agent operations - Full audit trail of every action an agent took - Deterministic replay for debugging agent behavior - Version history for every file, built in ## Dual Identity Model Storage treats humans and AI agents as equal participants. Both are "actors" with the same API surface and permissions model. ### Human Authentication ### Agent Authentication ### Same API, Different Auth No special "service account" or "bot mode". An agent is just another actor. ## Edge-First Design The entire application runs at the edge, as close to the client as possible. No origin server. No single region. V8 isolates distributed across every continent. ### How a Request Travels ### Traditional vs Edge ### Why Edge Matters - For AI agents: Agents in cloud functions have their own cold starts. Adding network round-trips to a distant origin makes tool calls slow. Edge keeps the API fast wherever the agent runs. - For humans: The web dashboard, file browser, and share links all load from the nearest edge. No matter where your team is located, the experience is the same. - For collaboration: When a human in Tokyo and an agent in Virginia share the same storage, both get fast responses. No single region becomes a bottleneck for the team. ## MCP: Native AI Integration Storage implements the Model Context Protocol as a first-class interface, not an adapter bolted on top. ### Tools ### MCP Architecture MCP tools and REST API share the same storage engine. A file uploaded via REST is immediately visible via MCP, and vice versa. ## Technology Stack ## Why This Architecture Suits AI Agents 1. No SDK required: plain HTTP. Any agent runtime can call it. 2. Deterministic responses: JSON with consistent schemas documented via OpenAPI. No HTML parsing. 3. MCP native: tools map directly to storage operations. 4. Event sourcing: agents can sync incrementally, not poll everything. 5. Content addressing: deduplication means agents don't waste storage re-uploading. 6. Edge-first: fast enough for tool calls inside LLM inference loops. Near-instant cold starts. 7. Dual identity: agents are first-class actors, not hacks on top of user accounts. 8. Scoped keys: agents get exactly the permissions they need, nothing more. 9. Audit trail: every agent action is logged and traceable. 10. Zero egress: agents can read files as often as they need without cost anxiety. ## Links - Developer Guide - API Reference - CLI Documentation - Pricing