File Storage

LibreChat supports multiple file storage strategies for different file types. Configure storage in librechat.yaml.

Storage Strategies

Three storage backends are available:

local: Store files on the server filesystem
s3: AWS S3 or S3-compatible storage (MinIO, Backblaze B2, etc.)
firebase: Firebase Cloud Storage

Configuration Formats

Legacy Format (Single Strategy)

Apply the same storage strategy to all file types:

fileStrategy: "s3"

Granular Format (Recommended)

Use different storage strategies for different file types:

fileStrategy:
  avatar: "s3"        # User/agent avatar images
  image: "firebase"   # Uploaded images in chats
  document: "local"   # Document uploads (PDFs, text files, etc.)

fileStrategy.avatar

string

default:"local"

Storage strategy for user and agent avatar imagesAvailable: local, s3, firebase

fileStrategy.image

string

default:"local"

Storage strategy for uploaded images in chatsAvailable: local, s3, firebase

fileStrategy.document

string

default:"local"

Storage strategy for document uploads (PDFs, text files, etc.)Available: local, s3, firebase

If not specified, all file types default to local storage

Local Storage

Stores files on the server’s filesystem.

fileStrategy: "local"
# or
fileStrategy:
  avatar: "local"
  image: "local"
  document: "local"

Local Storage Paths

Files are stored in different directories based on type:

Images: publicPath/images/userId/ (served statically)
Documents: uploads/userId/ (downloaded via API)

Configuration

No additional environment variables required. Files are stored in:

/app/client/public/images/  # Images
/app/api/uploads/           # Documents

Local storage is not recommended for production deployments with multiple instances or container orchestration (e.g., Kubernetes) as files are not shared across instances.

AWS S3 Storage

Store files in AWS S3 or S3-compatible services.

fileStrategy: "s3"
# or
fileStrategy:
  avatar: "s3"
  image: "s3"
  document: "s3"

Environment Variables

AWS_ACCESS_KEY_ID

string

required

AWS access key ID

AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

AWS_SECRET_ACCESS_KEY

string

required

AWS secret access key

AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

AWS_REGION

string

required

AWS region

AWS_REGION=us-east-1

AWS_BUCKET_NAME

string

required

S3 bucket name

AWS_BUCKET_NAME=librechat-files

AWS_ENDPOINT_URL

string

Custom endpoint URL for S3-compatible services

# MinIO
AWS_ENDPOINT_URL=https://minio.example.com

# Backblaze B2
AWS_ENDPOINT_URL=https://s3.us-west-002.backblazeb2.com

# Hetzner Storage Box
AWS_ENDPOINT_URL=https://hetzner.storage.box.com

AWS_FORCE_PATH_STYLE

boolean

default:"false"

Required for path-style S3-compatible providers

Set to true for MinIO, Hetzner, Backblaze B2, and other providers that don’t support virtual-hosted-style URLs (bucket.endpoint). Not needed for AWS S3.

AWS_FORCE_PATH_STYLE=true

S3-Compatible Providers

MinIO

AWS_ENDPOINT_URL=https://minio.example.com
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=minioadmin
AWS_BUCKET_NAME=librechat
AWS_REGION=us-east-1
AWS_FORCE_PATH_STYLE=true

Backblaze B2

AWS_ENDPOINT_URL=https://s3.us-west-002.backblazeb2.com
AWS_ACCESS_KEY_ID=your-b2-key-id
AWS_SECRET_ACCESS_KEY=your-b2-application-key
AWS_BUCKET_NAME=your-bucket-name
AWS_REGION=us-west-002
AWS_FORCE_PATH_STYLE=true

Hetzner Storage Box

AWS_ENDPOINT_URL=https://hetzner.storage.box.com
AWS_ACCESS_KEY_ID=your-storage-box-username
AWS_SECRET_ACCESS_KEY=your-storage-box-password
AWS_BUCKET_NAME=your-bucket-name
AWS_REGION=fsn1
AWS_FORCE_PATH_STYLE=true

File Organization

Files are organized in S3 by user ID and file type:

bucket-name/
├── images/
│   └── user-id/
│       └── file-id__filename.png
└── uploads/
    └── user-id/
        └── file-id__filename.pdf

Azure Blob Storage

Store files in Azure Blob Storage.

fileStrategy: "azure"

Azure Blob Storage uses the same configuration key as S3 in the YAML file. Configure via environment variables.

Environment Variables

AZURE_STORAGE_CONNECTION_STRING

string

required

Azure Storage account connection string

AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey;EndpointSuffix=core.windows.net

AZURE_CONTAINER_NAME

string

default:"files"

Azure Blob container name

AZURE_CONTAINER_NAME=librechat-files

AZURE_STORAGE_PUBLIC_ACCESS

boolean

default:"false"

Enable public access to blobs

AZURE_STORAGE_PUBLIC_ACCESS=false

Example Configuration

.env

AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=librechat;AccountKey=abc123...;EndpointSuffix=core.windows.net
AZURE_CONTAINER_NAME=files
AZURE_STORAGE_PUBLIC_ACCESS=false

Firebase Cloud Storage

Store files in Firebase Cloud Storage.

fileStrategy: "firebase"
# or
fileStrategy:
  avatar: "firebase"
  image: "firebase"
  document: "firebase"

Environment Variables

FIREBASE_API_KEY

string

required

Firebase API key

FIREBASE_AUTH_DOMAIN

string

required

Firebase auth domain

FIREBASE_PROJECT_ID

string

required

Firebase project ID

FIREBASE_STORAGE_BUCKET

string

required

Firebase storage bucket name

FIREBASE_MESSAGING_SENDER_ID

string

required

Firebase messaging sender ID

FIREBASE_APP_ID

string

required

Firebase app ID

Example Configuration

.env

FIREBASE_API_KEY=AIzaSyD...
FIREBASE_AUTH_DOMAIN=librechat-app.firebaseapp.com
FIREBASE_PROJECT_ID=librechat-app
FIREBASE_STORAGE_BUCKET=librechat-app.appspot.com
FIREBASE_MESSAGING_SENDER_ID=123456789
FIREBASE_APP_ID=1:123456789:web:abc123

File Organization

Files are stored with the following structure:

storage-bucket/
├── images/
│   └── user-id/
│       └── filename.png
└── uploads/
    └── user-id/
        └── filename.pdf

File Upload Limits

Configure file upload limits in librechat.yaml:

fileConfig:
  endpoints:
    assistants:
      fileLimit: 5
      fileSizeLimit: 10        # MB per file
      totalSizeLimit: 50       # MB total per request
      supportedMimeTypes:
        - "image/.*"
        - "application/pdf"
    openAI:
      disabled: true            # Disable file uploads
    default:
      totalSizeLimit: 20
    YourCustomEndpointName:
      fileLimit: 2
      fileSizeLimit: 5
  
  serverFileSizeLimit: 100      # Global server limit (MB)
  avatarSizeLimit: 2            # Avatar image limit (MB)
  
  imageGeneration:
    percentage: 100
    px: 1024
  
  clientImageResize:
    enabled: false
    maxWidth: 1900
    maxHeight: 1900
    quality: 0.92               # JPEG quality (0.0-1.0)

fileConfig.endpoints.<name>.fileLimit

number

Maximum number of files per request

fileConfig.endpoints.<name>.fileSizeLimit

number

Maximum size for individual file (MB)

fileConfig.endpoints.<name>.totalSizeLimit

number

Maximum total size for all files in request (MB)

fileConfig.serverFileSizeLimit

number

default:"100"

Global server file size limit (MB)

fileConfig.avatarSizeLimit

number

default:"2"

Avatar image size limit (MB)

Client-Side Image Resizing

fileConfig.clientImageResize.enabled

boolean

default:"false"

Enable client-side image resizing before upload

fileConfig.clientImageResize.maxWidth

number

default:"1900"

Maximum width for resized images (pixels)

fileConfig.clientImageResize.maxHeight

number

default:"1900"

Maximum height for resized images (pixels)

fileConfig.clientImageResize.quality

number

default:"0.92"

JPEG compression quality (0.0-1.0)

Use Cases

Privacy & Compliance

Keep sensitive documents on local storage for compliance:

fileStrategy:
  avatar: "s3"
  image: "s3"
  document: "local"  # Keep documents on-premise

Performance Optimization

Use S3 for avatars (fast global access) and Firebase for images (automatic optimization):

fileStrategy:
  avatar: "s3"
  image: "firebase"
  document: "s3"

Cost Optimization

Store frequently accessed avatars in S3, keep large documents local:

fileStrategy:
  avatar: "s3"
  image: "s3"
  document: "local"

Shared Links

Enable file sharing via public links:

ALLOW_SHARED_LINKS

boolean

default:"true"

Enable shared links feature

ALLOW_SHARED_LINKS_PUBLIC

boolean

default:"true"

Allow public shared links (accessible without authentication)

.env

ALLOW_SHARED_LINKS=true
ALLOW_SHARED_LINKS_PUBLIC=true

Static File Caching

Configure cache headers for static files:

STATIC_CACHE_MAX_AGE

number

default:"172800"

Browser cache duration in seconds (default: 2 days)

Only takes effect when NODE_ENV=production

STATIC_CACHE_S_MAX_AGE

number

default:"86400"

CDN/proxy cache duration in seconds (default: 1 day)

.env

NODE_ENV=production
STATIC_CACHE_MAX_AGE=172800   # 2 days
STATIC_CACHE_S_MAX_AGE=86400  # 1 day

Advanced Options

DISABLE_COMPRESSION

boolean

Disable Express-based compression

Use if you have another service doing compression

ENABLE_IMAGE_OUTPUT_GZIP_SCAN

boolean

Enable scanning and serving of gzipped images

Scans image folder on startup and keeps map in memory. Use carefully with large image counts.

.env

DISABLE_COMPRESSION=true
ENABLE_IMAGE_OUTPUT_GZIP_SCAN=true

Get Started

Core Features

Configuration

Deployment

User Management

Storage Strategies

Configuration Formats

Legacy Format (Single Strategy)

Granular Format (Recommended)

Local Storage

Local Storage Paths

Configuration

AWS S3 Storage

Environment Variables

S3-Compatible Providers

File Organization

Azure Blob Storage

Environment Variables

Example Configuration

Firebase Cloud Storage

Environment Variables

Example Configuration

File Organization

File Upload Limits

Client-Side Image Resizing

Use Cases

Shared Links

Static File Caching

Advanced Options

Build docs developers (and LLMs) love

Get Started

Core Features

Configuration

Deployment

User Management

​Storage Strategies

​Configuration Formats

​Legacy Format (Single Strategy)

​Granular Format (Recommended)

​Local Storage

​Local Storage Paths

​Configuration

​AWS S3 Storage

​Environment Variables

​S3-Compatible Providers

​File Organization

​Azure Blob Storage

​Environment Variables

​Example Configuration

​Firebase Cloud Storage

​Environment Variables

​Example Configuration

​File Organization

​File Upload Limits

​Client-Side Image Resizing

​Use Cases

​Shared Links

​Static File Caching

​Advanced Options

Build docs developers (and LLMs) love

Storage Strategies

Configuration Formats

Legacy Format (Single Strategy)

Granular Format (Recommended)

Local Storage

Local Storage Paths

Configuration

AWS S3 Storage

Environment Variables

S3-Compatible Providers

File Organization

Azure Blob Storage

Environment Variables

Example Configuration

Firebase Cloud Storage

Environment Variables

Example Configuration

File Organization

File Upload Limits

Client-Side Image Resizing

Use Cases

Shared Links

Static File Caching

Advanced Options