Active Storage
Built-in Rails file attachment system — attaches files to ActiveRecord models and stores them in cloud storage (S3, GCS, Azure Blob) or local disk. Active Storage features: has_one_attached :avatar / has_many_attached :documents in models, form with file_field, direct upload to S3 (bypasses Rails server), image transformation via Vips/ImageMagick (variant), file validation via custom validators or active_storage_validations gem, service configuration in config/storage.yml, background job for variant processing, mirroring between services, and CDN URL generation. Included in Rails since 6.0 with no additional gems required for basic usage.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Active Storage does not validate file content by default — uploaded files are stored as-is; add content_type validation to prevent agent apps from storing malware; never serve uploaded agent files from same domain as app (XSS via HTML upload). Use private S3 buckets with presigned URLs for sensitive agent documents. Virus scanning via ClamAV before processing agent uploads recommended.
⚡ Reliability
Best When
Your Rails agent app needs file attachments stored in S3 or GCS — Active Storage provides zero-configuration file management with direct upload, variants, and built-in Rails integration.
Avoid When
You need complex file processing pipelines beyond image variants, you're building a non-Rails app, or you need fine-grained control over storage metadata (Shrine is more powerful).
Use Cases
- • Agent document upload — class Agent < ApplicationRecord { has_many_attached :documents } stores agent knowledge base files to S3; form with file_field(:documents, multiple: true) uploads multiple agent documents; agent.documents.each { |doc| process_document(doc) } accesses attachments
- • Agent avatar with image variants — has_one_attached :avatar; agent.avatar.variant(resize_to_limit: [200, 200]).processed generates agent profile thumbnail; <%= image_tag agent.avatar.variant(resize_to_limit: [200, 200]) %> in view with automatic S3 URL
- • Direct upload for large agent files — direct_upload: true in file_field bypasses Rails server; large agent training documents upload directly to S3 from browser; reduces Rails server memory usage and upload timeout issues
- • Agent file URL generation — agent.document.url(expires_in: 1.hour) generates presigned S3 URL; agent.document.url with public service generates permanent CDN URL; rails_blob_path(agent.document, disposition: 'attachment') generates download link through Rails
- • Agent file validation — validates :document, blob: { content_type: ['application/pdf', 'text/plain'], size_range: 1.byte..10.megabytes } with active_storage_validations gem validates agent uploads before storage
Not For
- • Streaming large files — Active Storage serves files through Rails by default (memory buffering); for streaming large agent video files use direct S3/CloudFront URLs or streaming-capable proxy
- • Complex file processing pipelines — Active Storage does basic image transforms; for agent document parsing, OCR, or multi-step processing use Sidekiq jobs with specialized libraries
- • Non-Rails Ruby projects — Active Storage is Rails-only; for non-Rails file storage use AWS SDK directly or Shrine gem
Interface
Authentication
Cloud storage credentials via config/storage.yml (S3 access_key_id/secret_access_key, GCS credentials JSON). Use IAM roles in production instead of static keys. Presigned URLs provide time-limited access to private agent files.
Pricing
Active Storage is MIT licensed as part of Rails. S3/GCS/Azure storage backend costs are cloud provider pricing.
Agent Metadata
Known Gotchas
- ⚠ rails active_storage:install must be run — Active Storage requires 3 database tables (active_storage_blobs, active_storage_attachments, active_storage_variant_records); missing migration causes undefined table error; new Rails agent apps need rails active_storage:install && rails db:migrate before using attachments
- ⚠ Direct upload requires CORS configuration on S3 — direct_upload: true in form sends browser request directly to S3; S3 bucket must allow CORS from agent app origin; missing CORS config causes 'Access to XMLHttpRequest blocked' in browser; configure S3 CORS policy to allow PUT from agent app domain
- ⚠ Variant processing requires libvips or ImageMagick — image variant transform requires vips (faster, recommended) or mini_magick; missing system dependency causes ActiveStorage::InvariableError; Docker agent images must install libvips-dev or imagemagick; Rails 7+ defaults to vips, older docs show ImageMagick
- ⚠ Attaching inside transaction can cause orphaned blobs — agent code that creates attachments inside a transaction where the record save fails leaves orphaned blobs in S3; Active Storage blob is persisted before ActiveRecord record; implement cleanup job or use after_commit hook for agent attachment post-processing
- ⚠ Service URL expiry affects caching — agent.document.url generates presigned URL valid for 5 minutes by default; caching these URLs in Redis or client-side causes expired link errors; generate URLs on-demand rather than storing; configure expires_in: 1.week for agent download links with less sensitive content
- ⚠ has_many_attached purge deletes all attachments — agent.documents.purge deletes ALL attached documents permanently from storage; has_one_attached.attach replaces previous attachment and schedules old blob for deletion; agent code purging attachments must implement soft-delete or backup strategy for recoverable agent documents
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Active Storage.
Scores are editorial opinions as of 2026-03-06.