Most apps need to handle files: a profile photo, a receipt, a document, a video. Runable wires up the whole flow ask for the camera, pick from the library, upload in the background, cache for fast display next time, and resume uploads after a network drop.Documentation Index
Fetch the complete documentation index at: https://docs.runable.com/llms.txt
Use this file to discover all available pages before exploring further.
What you can do
Take a photo or video
Open the camera in-app. Pick still photos, square crops, video clips, or scan a barcode. Front and back camera, flash, and tap-to-focus all supported.
Pick from the library
Choose one or many photos and videos. The system picker on iOS 14+ and Android 13+ shows only what the user grants, so they keep their photo library private.
Pick any file
PDFs, spreadsheets, audio, anything else. The user picks from Files, Google Drive, iCloud Drive, Dropbox whatever they have set up on their phone.
Upload in the background
Big uploads continue when the user backgrounds the app. Resume automatically if the connection drops. Progress shows in your UI.
Cache for instant display
Once a remote image or file has been downloaded, the next view is instant from the local cache. No spinner, no flash of placeholder.
Share content out
Open the system share sheet so users send files to Messages, Mail, Notes, or any other app on their phone.
How file flow works
Add file handling to your app
Describe what you want users to do with files
Profile photo upload: tap the avatar to open a sheet with “Take photo” and “Pick from library.” Image is cropped to a square, compressed to a max of 2 MB, uploaded, and shown as the avatar everywhere immediately.Or:Add a receipts feature: a list of uploaded receipts with date, vendor, amount, and a thumbnail. Tap the plus button to take a photo of a new receipt; the app uses OCR to fill in the vendor and amount fields, which the user can edit before saving.The agent builds the flow, the permissions, the upload, and the display.
Write the permission prompts
On first use, the system asks for camera and photo library access. The reason string shown in the prompt is set by your app Apple and Google require it to be clear and specific.The agent generates sensible defaults:
“Cairn uses your camera to take photos of your habits.” “Cairn uses your photo library so you can pick existing photos.”Override either with: change the camera permission prompt to “Cairn needs camera access so you can scan your books’ barcodes.”
Compress before uploading
A raw phone photo can be 510 MB. For most apps that is wasteful. The agent compresses images by default:
- Avatars: square crop, 500×500, target 100 KB.
- Photo posts: resize to 1080px on the long side, target 500 KB.
- Document scans: keep aspect, target 1 MB, prefer sharpness.
Upload
Tapping save kicks off the upload. The agent shows a progress indicator in the spot where the file will end up (a spinner over the avatar, a progress bar on the receipt row). The upload continues even if the user navigates away or backgrounds the app.If the connection drops mid-upload, the upload resumes from where it left off when the network comes back. The user does not have to retry.
Display next time
Once uploaded, the file lives in cloud storage and your app references it by URL. The next time anyone views the same image, the phone serves it from a local cache no network call, no spinner.The cache is bounded (the agent defaults to about 200 MB per app) and evicts the least-recently-used files when full. Users never have to “clear cache” manually.
Image transformations
The agent can resize, crop, or compress images on the fly without re-uploading.| Transform | What it does | When to use |
|---|---|---|
width/height | Resize to fit, preserving aspect ratio | Showing thumbnails of large images |
crop | Fill a box, cropping the longer side | Square avatar from a portrait photo |
quality | Compress to a target quality | Saving bandwidth on data-light screens |
format | Convert between JPEG, PNG, WebP | Smaller files for the same visual quality |
blur | Gaussian blur | Loading placeholders, sensitive content |
Camera features
For apps that use the camera as the main input, ask for the specific behavior you need:Barcode scanning
Scan ISBN, QR, UPC, Code 128, and most others. The agent overlays a viewfinder rectangle and fires a haptic on a confirmed scan.
Document scan
Detect a paper’s edges, square it up, and produce a cropped PDF or image. Multi-page support.
Text recognition
OCR pull text out of a photo. Handles printed and handwritten text, multiple languages, vertical alignment.
Custom overlay
A custom camera screen with your own brand, guides, and capture button. Useful for product photos, before/after shots, ID verification.
Share content out
Users often want to send a file out of your app. The system share sheet handles every destination on the phone Messages, Mail, Notes, Drive, Slack, anything they have installed. Ask: add a share button on each receipt that lets the user send the image and a one-line summary via the system share sheet. The agent wires up the share content and the right title for the share sheet.What you can see
The project dashboard surfaces file storage stats:- Storage used total, and per user
- Upload success rate what percentage of upload attempts succeed
- Average upload time by file size bucket
- Cache hit rate how often the phone served from cache instead of fetching
- Largest 100 files useful for spotting users who are abusing the storage
What you cannot do
- Access photos without the user’s permission. Both stores require an explicit permission grant. There is no workaround.
- Upload arbitrarily large files from a phone in one go. Mobile networks cap practical uploads at around 11.5 GB per file. For larger files, the agent chunks the upload and resumes between sessions.
- Read other apps’ files. The phone sandboxes each app’s storage. You only see what the user explicitly hands to your app via the picker.
- Persist content beyond the user’s account. When a user deletes their account, their files are deleted too. There is no path to keep files after deletion.
Next steps
Mobile App Data
Pair files with structured data on the device and server.
Push Notifications
Notify the user when a file upload finishes in the background.
Environment Variables
Switch storage endpoints between dev, preview, and production.
Analytics
Watch upload success rates and cache performance in production.