Rails · FileHutch docs

You need a project with an avatars upload policy. Create one under Upload policies in the dashboard, or let your coding agent do it.

Install the gem#

Gemfile

gem "file_hutch"

Stdlib only at runtime. The Rails integration switches itself on when Rails is present.

Run the installer#

Terminal

bin/rails generate file_hutch:install

Writes an initializer, mounts the engine at /file_hutch for browser uploads, and pins the Stimulus controller. Then set your project key:

Terminal

# Dashboard → API keys. Shown once.
export FILE_HUTCH_API_KEY=fh_…

Add the column and the attachment#

Terminal

bin/rails generate file_hutch:attachment User avatar

That adds a single users.avatar_file_id string column. No blobs table, no attachments table, no service configuration.

app/models/user.rb

class User < ApplicationRecord
  has_hutch :avatar, policy: "avatars"
end

Use it#

Ruby

# Assign an uploaded file. Goes to storage on save.
user.avatar = params[:avatar]

# Read it back
user.avatar_url                         # public policies
user.avatar_signed_url(expires_in: 600) # any file
user.avatar_transform_url("thumb")      # a named transform

# Remove it, remotely and locally
user.purge_avatar

A wrong content type or an oversized file becomes a validation error before anything leaves your server — the policy is checked locally first.

Upload from the browser#

Optional, and worth it for anything large: bytes go from the browser straight to storage, and only two small JSON calls touch your app. Your API key never reaches the page.

config/initializers/file_hutch.rb

# Closed until you say who may upload.
FileHutch.config.authorize_direct_upload = ->(controller, policy) do
  controller.current_user.present? && policy == "avatars"
end