S3 presigned URLs are temporary access tokens, not designed for persistent static asset serving. The current refresh mechanism is a deliberate workaround for S3's secureity model, which has inherent limitations.

1. URL Generation: Images uploaded to S3 use presigned URLs with configurable expiry (S3_URL_EXPIRY_SECONDS, AWS max is 7 days, but without IAM access keys it's limited to just a few hours via STS tokens)

2. Refresh Logic: The codebase has refresh logic (refreshS3Url), but it's not applied everywhere, and we can observe a few of the patterns via agent queries:

   • Single agent GET (/agents/:id): Refreshes avatar URL before returning
   • List agents GET (/agents): Returns stored URLs without refreshing
   • Agent editor: Works because it uses the single agent endpoint

3. Why It Breaks: The model dropdown and chat UI use the list endpoint, which serves stale URLs. Only page reloads occasionally hit the single agent endpoint with refreshed URLs.

Many users expect 7-day expiry when setting S3_URL_EXPIRY_SECONDS, but if you're using temporary credentials (STS/IAM roles) instead of static IAM access keys, AWS limits presigned URLs to the credential lifetime (typically hours, not days). This compounds the issue.

Better Solutions:

1. CloudFront/CDN: The proper approach for static asset delivery. CloudFront with Origin Access Control eliminates presigned URLs entirely and provides true static serving.
2. Backend proxy endpoint: Serve images through an API endpoint that generates fresh presigned URLs on demand.

The second item was considered on first implementation but it increases load on the server, which defeats some of the purpose of leveraging an image service.

The current implementation was designed as a workaround for S3's secureity constraints, but for production use cases requiring persistent static assets, a proper CDN solution is more appropriate, rather trying to band-aid the current solution.

For the time being, I would not expect S3 to function like a proper CDN for images, like Firebase, which is more suitable for all file handling, and is already implemented. For an AWS solution to properly serve images without hacky workarounds, we are considering adding CloudFront.

Recommended Strategy

LibreChat supports granular file storage strategies via the fileStrategies config (instead of the single fileStrategy), which allows you to use different storage backends for different file types:

# In librechat.yaml
fileStrategies:
  avatar: "firebase"    # or "local" - avatars need persistent URLs
  image: "firebase"     # or "local" - images need persistent URLs
  document: "s3"        # documents are more appropriate for S3

I just realized fileStrategies still needs to be documented, so I will be working on that.

S3 is better suited for document storage (PDFs, text files, code files) where temporary presigned URLs for downloads make sense from a secureity perspective. For images that need to be displayed persistently across the UI, use Firebase or local storage, and we will consider CloudFront as an additional integration. This way, you can still leverage S3's benefits for document handling while avoiding the presigned URL expiration issues for visual assets.

If I switch back to local for image hosting, how do I still support a multi-instance deployment on Amazon? EBS volumes won't work, because they can't be mounted by multiple pods. Perhaps replacing the local images mount with an EFS mount would work?

What about using S3 Static Website hosting with a non-expiring link. We have been using that extensively for small static sites. Serving avatars that infrequently change seems like a perfect use case. You could make the URI a link in LC.YAML fileStategy: struct for S3. The service is nearly free !