File storage for agents—and the apps they build.

Generate an API key in the dashboard, then install Folder Stack with that key. F-stack saves the configuration locally, gives your agent Folder skills, and provides read-only smoke checks.

curl -fsSL https://www.folder.md/fstack/install.sh | FOLDER_API_KEY='fmd_live_your_api_key' FOLDER_API_BASE='https://www.folder.md/api/v1' bash

Verify the connection, then list the Folders visible to the key:

~/.fstack/bin/fstack smoke

curl https://www.folder.md/api/v1/folders \
  -H "Authorization: Bearer $FOLDER_API_KEY"

Keep keys out of source control. Use environment variables or your deployment platform's secret manager. Folder shows a newly created key once.

The same storage primitives support two clear jobs. You can start with either and add the other later.

Create a Folder for a project or workflow, scope an API key to it, and connect through MCP, the CLI, or REST. Every meaningful directory can carry a folder.md instruction file so agents find local operating context alongside the files it governs.

Install Folder Stack and configure Folder MCP on this machine.
Use my API key from FOLDER_API_KEY; never print or commit it.
Preserve unrelated MCP servers, run the read-only smoke test,
and tell me which Folder workflows are now available.

For broad backup, audit first and upload only approved roots. F-stack includes setup, smoke, sync, backup, restore, machine-audit, and the umbrella folder-dream workflow.

Use Folder when your app needs durable file bytes and file-oriented metadata. A private photo app, for example, can put original images in Folder while a database stores users, follows, captions, likes, and feed ordering.

1. Create one Folder for the app or for each tenant boundary your design requires.
2. Create the narrowest useful key: read, write, or admin.
3. Keep the key server-side; do not expose it in browser or mobile bundles.
4. Upload bytes with a stable path, then store the returned Folder/file IDs in your database.
5. Use signed webhooks to update derived application state asynchronously.

curl -X POST "https://www.folder.md/api/v1/folders/$FOLDER_ID/files" \
  -H "Authorization: Bearer $FOLDER_API_KEY" \
  -H "X-File-Path: /photos/$USER_ID/$PHOTO_ID.jpg" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Choose encryption deliberately: standard uploads are capped at 100 MB and use Folder application-layer encryption. Direct single-part uploads can approach 5 GiB (subject to Folder quota), but use R2-managed AES-256 at rest and bypass Folder application-layer encryption. Multipart/resumable upload and media-delivery primitives are not active yet.

Folder stores file bytes, paths, hashes, versions, tags, and file activity. It does not replace relational queries, transactions, authorization models, or application state.

Pair Folder with Supabase/Postgres, Convex, SQLite/PGlite, or the database your application already uses. Think file layer + database, not one instead of the other.

F-stack is the portable local layer around the API: an installer, helper CLI, agent skills, command shims, routing guidance, and smoke tests. The install root is ~/.fstack.

~/.fstack/bin/fstack smoke
~/.fstack/bin/fstack capabilities
~/.fstack/bin/fstack route "back up this project safely"
~/.fstack/bin/fstack backup-prompt
~/.fstack/bin/fstack restore-prompt
~/.fstack/bin/fstack dream-prompt

Run the published MCP package in any MCP-compatible client. Set the key in the client's environment rather than embedding it in prompts.

{
  "mcpServers": {
    "folder": {
      "command": "npx",
      "args": ["-y", "@foldermd/mcp"],
      "env": { "FOLDER_API_KEY": "fmd_live_..." }
    }
  }
}

Core tools include folder_list, folder_tree, file_list, file_read, file_write, file_update, publish controls, activity reads, subfolders, and agent capability routing.

The CLI covers Folder and file operations plus sync, selected-machine backup, restore, audit, and agent-context workflows.

npm install -g @foldermd/cli
export FOLDERMD_API_KEY="$FOLDER_API_KEY"

folder folders list
folder files list "$FOLDER_ID"
folder files upload "$FOLDER_ID" ./report.pdf /reports/report.pdf

Send a Folder API key as a Bearer token. Folder-scoped keys can only access their Folder. Permissions are additive: read, write, and admin.

curl https://www.folder.md/api/v1/folders \
  -H "Authorization: Bearer $FOLDER_API_KEY"

The canonical base URL is https://www.folder.md/api/v1. Call the www origin directly so redirects do not affect authorization headers.

Standard uploads accept multipart form data or a raw request body with X-File-Path. Creating a file at an existing path returns 409; replacement is explicit with PUT.

Direct single-part upload

For larger browser or app uploads, initiate the request on your trusted server, send the bytes directly to the returned presigned R2 URL, and complete the upload with its token.

curl -X POST "https://www.folder.md/api/v1/folders/$FOLDER_ID/direct-uploads" \
  -H "Authorization: Bearer $FOLDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/photos/user/photo.jpg","content_type":"image/jpeg","size":12345}'

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

curl -X POST "https://www.folder.md/api/v1/folders/$FOLDER_ID/direct-uploads/complete" \
  -H "Authorization: Bearer $FOLDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{"token":"$UPLOAD_TOKEN"}"

The URL expires after 15 minutes. Completion verifies object size, enforces Folder quota, creates metadata, and emits file.created. Direct upload is not S3 API compatibility; it is a Folder API flow that returns a short-lived object upload URL. Browser PUTs also depend on the Folder R2 CORS policy allowing your deployed origin, so verify that origin before shipping a client upload flow.

Folder signs webhook payloads with HMAC-SHA256. Delivery is asynchronous and retries with backoff; successful API mutation does not guarantee the receiver has already accepted the event.

Events: file.created, file.updated, file.deleted, subfolder lifecycle, API-key lifecycle, and webhook lifecycle.

Use capability discovery instead of assuming large-file or backup behavior. It reports single_part_direct_active_multipart_designed_not_active: direct single-part PUT is active, while multipart/resumable upload remains a designed contract rather than an active runtime feature.

The zero-dependency TypeScript SDK wraps the same REST API. Environment-based configuration keeps examples portable across local agents and deployed apps.

import { FolderMD } from "@foldermd/sdk"

const folder = new FolderMD({
  apiKey: process.env.FOLDER_API_KEY!,
})

const folders = await folder.folders.list()

There is no published first-party Python SDK today. Python applications should call the REST API directly using the OpenAPI contract.

Paths are Unix-style, at most 500 characters, and may not contain .. or //. File names are capped at 255 characters.

Folder is backed by Cloudflare R2, but the public Folder API is not currently an S3-compatible endpoint. Use the Folder REST API, SDK, CLI, or MCP contract.

API errors use standard HTTP status codes with a JSON error response. Common cases:

Use these public artifacts for code generation, agent context, and contract inspection: