Cloud Storage
Connect self-hosted media servers and stock catalogs, browse them in Library, and attach cloud media to tasks.
Cloud storage lets you browse connected media libraries from the desktop app and attach media to an agent task without downloading it manually first.
What You Can Connect
| Connection | Providers | Best For |
|---|---|---|
| Self-hosted media | Immich, PhotoPrism | Personal photo and video libraries on your own server |
| Stock catalog | OpenVerse, Unsplash, Pexels | Licensed images and videos for creative work |
OpenVerse can be added without an API key. Unsplash and Pexels require their own API keys.
Connect Self-Hosted Media
- Open Settings > Connectors
- Find Cloud storage
- Click Self-hosted media
- Choose Immich or PhotoPrism
- Enter a Display name, Base URL, and API key
- Click Test connection
- Click Create connection
If you connect Immich and the server version may include a known API key security issue, the app shows a warning. Upgrade the server before using that connector for sensitive libraries.
Connect a Stock Catalog
- Open Settings > Connectors
- Find Cloud storage
- Click Stock catalog
- Choose OpenVerse, Unsplash, or Pexels
- Enter a Display name
- Enter an API key when the provider requires one
- Click Test connection
- Click Create connection
Stock catalog connections are read-only. When an attached item requires attribution, the app adds attribution text to your prompt automatically.
Browse Cloud Storage in Library
- Open Library
- Select the Cloud storage tab
- Choose a connection at the top of the page
- Search with Search media...
- Filter by All, Images, Videos, Audio, Documents, or Folders
- For stock catalogs, use the License filter
- Click a media item to preview it
Media with capture dates appears in a timeline view. Other files appear in a grid or list. The preview can show file details, media details, location, camera information, people, tags, and an Open in source link when the provider supports it.
Attach Cloud Media to a Task
- Start a task from Home or an existing task thread
- Open the attachment menu in the chat input
- Click Cloud media
- Choose a connection
- Search or browse folders
- Use Search options for Immich filters like place, camera, date range, favorites, archive, album state, file name, description, or OCR text
- Preview any item if you need to check details
- Select one or more items
- Click Attach selected
If you select a folder, the app attaches the files inside that folder. Stock catalog attribution is added to the prompt so the agent has the required credit text.
When an attached item comes from Immich, the agent also receives source details for publishing. If you ask it to publish or save an edited result back to that library, it can route the job to the matching Immich destination instead of using an unrelated photo service.
Publish Back to Immich
When the publish pipeline is enabled, Immich can be used as a publish destination for generated or edited media.
Use this workflow when an agent edits media that originally came from Immich:
- Attach the Immich source item to the task
- Ask the agent to create or edit the media
- Review the generated output
- Open the publish action
- Choose the matching Immich destination
- Add title, description, album, or other destination metadata when available
- Submit the publish job and approve it if required
The publish pipeline keeps source provenance and destination history so you can tell which generated output was sent back to the media library.
LAN Path Mappings for Immich
LAN path mappings let the desktop app read Immich originals from a mounted local share instead of streaming them through the server.
Use this when your Immich server stores originals on a NAS, SMB share, NFS mount, synced folder, or Tailscale-reachable machine that is also mounted on your desktop.
- Open Settings > Connectors
- In Cloud storage, connect Immich first
- Under LAN path mappings, click Add mapping
- Enter the Immich path prefix
- Enter the Local mount path
- Keep Verify before saving enabled when a sample asset is available
- Click Save mapping
If the share is reachable over Tailscale, mount it in your operating system first and use that mounted path. Verified mappings appear as LAN bridge active.
Search Options
Immich supports advanced search options:
| Option | What It Does |
|---|---|
| Context | Search descriptions and context |
| File name or extension | Find files by name, such as IMG_1234.jpg |
| Description | Search descriptions |
| OCR | Search text detected inside images |
| Place | Filter by country, state, or city |
| Camera | Filter by make, model, or lens model |
| Start date / End date | Filter by capture date |
| Favorites | Show favorite media |
| Archive | Include archived media |
| Not in any album | Find media that has not been placed in an album |
Safety Notes
- Self-hosted media URLs are tested from your desktop
- Local network URLs are allowed only for self-hosted media connection setup
- Public self-hosted URLs must use HTTPS
- Local path mappings must point to real directories and are checked before use
- Stock catalog results keep license and attribution details visible
Learn More
- Desktop Application -- Main app overview and settings
- Media Generation -- AI-generated images and videos
- Publish Pipeline -- Send generated media to cloud storage, Immich, WebDAV, or social destinations
- Workspace Security -- Workspace isolation and safety