How to Implement the Fastio API in Ruby on Rails

File sharing is the practice of distributing digital files between users over a network, typically using cloud storage or direct transfer services. Modern file sharing platforms support files from a few kilobytes to hundreds of gigabytes, with features like access controls, versioning, and real-time collaboration. For development teams, choosing the right file sharing method directly affects application performance and feature velocity.

Implementing the Fastio API in Ruby on Rails allows developers to natively integrate intelligent, multi-agent workspaces into their traditional web applications. Instead of merely uploading files to a passive S3 bucket, a Rails application using Fastio creates dynamic workspaces where uploaded files are automatically indexed for RAG (Retrieval-Augmented Generation), immediately searchable by meaning, and accessible to AI agents via the Model Context Protocol (MCP).

This integration bridges the gap between legacy monoliths and modern AI workflows. By adopting Fastio, Rails developers can provide their users with enterprise-grade file management that is inherently understood by AI, without having to build complex vector databases or chunking pipelines from scratch.

Active Storage makes it easy to attach files to Active Record objects, but it is fundamentally just a bridge to commodity storage like Amazon S3, Google Cloud Storage, or Microsoft Azure Storage. Most Rails file upload guides stop at basic S3 integrations, completely missing agentic workspace workflows.

When you only use S3, your application treats files as dead weight. You have to build your own vector databases, indexing pipelines, and agent communication layers if you want AI to interact with those files. Every time a user uploads a PDF or a video, your backend must process, transcribe, chunk, and embed the content before an LLM can even read it. This creates massive overhead and technical debt.

Fastio replaces this passive storage model. Every workspace in Fastio provides a free agent tier featuring multiple of storage, a multiple maximum file size limit, and multiple monthly credits with no credit card required. When you upload a file through the Fastio API, it is instantly available to multiple MCP tools via Streamable HTTP and SSE. Your Rails application no longer just stores data; it hosts an intelligent environment where agents and humans share the same tools and context.

Ready to upgrade your Rails storage?

Get 50GB of free storage, access to 251 MCP tools, and built-in RAG for your AI agents.

Sign Up Free

Integrating Fastio into your Rails application requires configuring the SDK and establishing secure authentication. Follow these steps to initialize the Fastio API client and prepare your application for agentic workflows.

Step 1: Install the gem Add the Fastio Ruby SDK to your Gemfile.

gem 'fastio-ruby'

Run bundle install to download and install the dependency in your environment.

Step 2: Configure environment variables Protect your API keys by storing them in your .env file or your preferred credential management system. You will need your Fastio API key and the Organization ID.

FASTIO_API_KEY=sk_test_your_api_key_here
FASTIO_ORG_ID=org_your_organization_id

Step 3: Create an initializer Create a new file at config/initializers/fastio.rb to initialize the client globally across your Rails application.

require 'fastio'

Fastio.configure do |config|
  config.api_key = ENV.fetch('FASTIO_API_KEY')
  config.organization_id = ENV.fetch('FASTIO_ORG_ID')
  config.max_retries = 3
  config.timeout = 30
end

# Make the client available globally
Rails.application.config.fastio_client = Fastio::Client.new

This setup ensures that your Rails application can communicate with the Fastio API safely, handling rate limits and connection retries automatically while keeping your credentials secure.

Once the client is configured, you can programmatically provision workspaces. Unlike traditional folders, Fastio workspaces are collaborative environments built for both humans and AI agents.

To create a workspace when a new project is initialized in your Rails app, you can wrap the API call in a service object:

class WorkspaceService
  def self.create_project_workspace(project)
    client = Rails.application.config.fastio_client
    
    workspace = client.workspaces.create(
      name: "Project Workspace: #{project.name}",
      description: "Auto-generated workspace for project #{project.id}",
      intelligence_mode: true
    )
    
    project.update(fastio_workspace_id: workspace.id)
    workspace
  end
end

By setting intelligence_mode: true, you ensure that any file uploaded to this workspace is automatically indexed. There is no need to configure a separate vector database or embedding pipeline. Toggle Intelligence Mode on a workspace, files are auto-indexed, ask questions with citations natively through the API.

Handling file uploads in Rails typically involves form data and multipart requests. With Fastio, you stream the file directly to the workspace, ensuring that memory consumption remains low on your web servers.

class DocumentsController < ApplicationController
  def create
    workspace_id = current_project.fastio_workspace_id
    file_io = params[:document][:file].tempfile
    filename = params[:document][:file].original_filename
    
    client = Rails.application.config.fastio_client
    
    # Upload the file directly to the Fastio workspace
    upload = client.files.upload(
      workspace_id: workspace_id,
      file: file_io,
      filename: filename
    )
    
    flash[:notice] = "File uploaded and indexed for AI agents."
    redirect_to project_path(current_project)
  end
end

Once uploaded, you can assign an AI agent to the workspace using the OpenClaw integration or by provisioning access via the MCP server. Install via clawhub install dbalve/fast-io to get multiple tools with zero-config, natural language file management. This allows agents to read, summarize, and edit the files asynchronously while your human users interact with the UI.

According to G2, over 60% of all corporate data is stored in the cloud. As applications modernize, simply storing this data is no longer enough; it must be actionable and accessible to machine intelligence.

Also, according to BuiltWith, there are currently 565,045 live websites using Ruby on Rails. For these hundreds of thousands of applications, transitioning from passive storage to intelligent workspaces is a critical modernization step. Integrating AI workspaces directly into monolithic frameworks like Rails is a top priority for modernizing legacy applications. By utilizing the Fastio SDK, teams can add next-generation capabilities without rewriting their entire application architecture.

For complex, multi-agent systems, you need robust concurrency controls and event-driven architecture. Fastio provides both through Webhooks and File Locks natively through the API.

Handling Concurrent Multi-Agent Access When multiple agents or humans attempt to edit the same file, you can acquire locks to prevent conflicts in multi-agent systems. This ensures data integrity even when tasks run in parallel.

def update_document(file_id, new_content)
  client = Rails.application.config.fastio_client
  lock = client.files.acquire_lock(file_id)
  
  begin
    client.files.update(file_id, content: new_content)
  ensure
    client.files.release_lock(file_id, lock.id)
  end
end

Using Webhooks for Reactive Workflows Get notified when files change to build reactive workflows without polling. Fastio sends an HTTP POST request to your Rails application whenever a file is created, updated, or deleted.

class FastioWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token
  
  def receive
    event = params[:event]
    
    if event[:type] == 'file.created' && event[:actor] == 'agent'
      ProcessAgentOutputJob.perform_later(event[:file_id])
    end
    
    head :ok
  end
end

One of the most powerful features of the Fastio API is the ability to bypass local server I/O entirely. Pull files from Google Drive, OneDrive, Box, Dropbox via OAuth without routing the bandwidth through your Rails application servers.

def import_from_drive(drive_url, workspace_id)
  client = Rails.application.config.fastio_client
  
  job = client.imports.create_from_url(
    workspace_id: workspace_id,
    url: drive_url,
    provider: 'google_drive'
  )
  
  job.id
end

This architectural pattern offloads the heavy lifting from your application directly to Fastio infrastructure. Your Rails app simply manages the state and displays the results to the user once the import completes. For B2B SaaS applications, you can use the API to let agents create organizations, build workspaces and shares, and transfer to human clients. The agent keeps admin access, ensuring smooth handoffs.