Storage

Store files, images, and attachments alongside your Crow data. Storage uses S3-compatible object storage (Garage, or any S3 service) so your files stay on your own infrastructure.

What is this?

Crow Storage gives your AI assistant the ability to save and retrieve files. It connects to the File Storage (Garage) extension (or any S3-compatible service) running alongside your Crow server.

Files are organized by type — images, documents, audio, attachments — and accessible through MCP tools, HTTP endpoints, or the Crow's Nest file browser.

Why would I want this?

• Project attachments — Save PDFs, datasets, and images alongside your projects
• Blog assets — Upload images for blog posts without needing a separate hosting service
• File sharing — Share files with connected peers through the existing P2P sharing system
• Backup — Keep important files in a self-hosted storage layer you control

Setup

Install File Storage (Garage) from Extensions in the Crow's Nest. Crow generates every key and token it needs, saves them in Settings → Passwords, and connects its storage tools to it — there is nothing to type.

• Where the files live: by default in a Docker volume on this machine. To keep them in a folder on another local disk, set GARAGE_DATA_PATH when installing (not a network share or a USB drive mounted through FUSE).
• Sharing with paired Crow instances: set GARAGE_BIND_ADDR to this machine's tailnet IP and S3_ENDPOINT to the same address with port 3900. The admin API (port 3903) always stays on this machine.
• No web console: browse and manage files in the Crow's Nest Files page.

Crow creates and manages its bucket (crow-files) automatically — no bucket setup needed.

Already have S3 somewhere else?

Any S3-compatible service works. Configure it in Settings → Shared Storage (it replicates to paired instances and takes precedence over .env), or set S3_ENDPOINT, S3_ACCESS_KEY and S3_SECRET_KEY in .env.

MinIO is deprecated — and its images are no longer published

Garage has been the default object storage since 2026-11-05. MinIO's public images are gone: Docker Hub and Quay refuse anonymous pulls as of that date, so MinIO can no longer be installed (nor pulled by a compose profile on a machine that does not already have the image). An existing MinIO install keeps running — start it with docker compose --profile minio-legacy up and keep the older MINIO_* settings, which are still read when no S3_* setting is present. Its data does not change; see Full Setup for the switch.

Uploading Files

Through your AI

Ask Crow to upload a file:

"Upload this image to storage"

"Save the PDF at ~/Downloads/paper.pdf to my research files"

Crow uses the crow_upload_file tool behind the scenes.

Through HTTP

Upload via the gateway's HTTP endpoint:

curl -X POST http://localhost:3001/storage/upload \
  -F "file=@photo.jpg" \
  -H "Authorization: Bearer YOUR_TOKEN"

Through the Crow's Nest

Open the Files panel in the Crow's Nest and use the upload button. You can drag and drop files directly.

Browsing Files

Ask Crow to list your files:

"Show me my stored files"

"List all images in storage"

Or browse them visually in the Crow's Nest Files panel.

Getting File URLs

To use a stored file (for example, in a blog post or shared document):

"Get the URL for header-image.jpg"

Crow generates a presigned URL that expires after a configurable period (default: 1 hour). This keeps your files private while allowing temporary access.

Storage Quotas

Crow enforces a configurable storage quota (default: 5 GB / 5120 MB). Check your usage:

"How much storage am I using?"

The crow_storage_stats tool returns current usage, file count, and remaining quota. Adjust the quota in your .env:

CROW_STORAGE_QUOTA_MB=2048

Supported File Types

Storage uses a blocklist approach — most file types are accepted, and only executable types are blocked. This means you can upload virtually any file format, including:

• Images: JPEG, PNG, GIF, WebP, SVG, TIFF, BMP, ICO
• Documents: PDF, plain text, Markdown, HTML, Office documents (DOCX, PPTX, XLSX)
• Data: JSON, CSV, XML, YAML
• Audio: MP3, WAV, OGG, FLAC, AAC
• Video: MP4, WebM, AVI, MKV
• Archives: ZIP, TAR, GZ, 7z, RAR

Files with unknown or unrecognized MIME types are also allowed.

The following executable MIME types are blocked:

• application/x-executable
• application/x-msdos-program
• application/x-msdownload
• application/x-sh
• application/x-shellscript
• application/x-bat
• application/x-msi

Unlocked Capabilities

When S3 storage is configured, it enables capabilities across the platform — not just file uploads:

• Message attachments — Send images, documents, and files in all Messages panel conversations (peer messages, AI chat, and bot chat). Files are uploaded to S3 and delivered via presigned URLs.
• Bot vision — Image attachments sent to bots are routed through a vision model for analysis, enabling bots to understand photos, receipts, screenshots, and documents.
• Blog assets — Upload header images and inline media for blog posts without needing a separate image host.
• Project files — Attach PDFs, datasets, and reference materials to research projects.
• File sharing — Share files with connected peers through the existing P2P sharing system.

Storage is optional — Crow works without it. But configuring Garage unlocks these features with no additional setup.

Deleting Files

"Delete the file old-draft.pdf from storage"

Deletion is permanent. Files are removed from both object storage and the database index.

Under the Hood

Curious how presigned URLs, quotas, and the S3 client work internally? See the Storage Server architecture.