Files User Guide
Last updated: 2026-05-21 Module: Files (the files service) Audience: Workspace members, admins, and guest users
Overview
The Files module provides workspace members with a centralized way to browse, upload, organize, share, download, and manage files and folders. It supports large file uploads via multipart upload, real-time progress tracking, public share links with expiration, and granular permission controls.
Navigation and Interface
Browser Layout
The Files browser is organized into these key areas:
| Area | Description |
|---|---|
| Header | Search bar, view toggles (grid/list), sort options |
| Tab Bar | All Files, Recent, Starred, Bin tabs (feature-gated) |
| Breadcrumb | Shows current folder path; click to navigate up |
| File List | Grid or list view of files and folders |
| Action Bar | Upload Files, Upload Folder, New Folder buttons |
Tab Navigation
| Tab | Purpose | Access |
|---|---|---|
| All Files | Browse all files in current folder | All workspace members |
| Recent | Files and folders updated in the last 30 days | All workspace members |
| Starred | Files and folders marked as favorite | Requires files.starred feature flag |
| Bin | Soft-deleted items pending permanent delete or restore | Requires files.bin feature flag |
Breadcrumb Navigation
Breadcrumbs show the folder hierarchy path. Each segment is clickable:
Files > Projects > Q1 2025 > Design Assets
Click any segment to jump directly to that folder level.
Browse Files
Accessing Files
- Click All Files in the tab bar
- Navigate folders by clicking folder names or using breadcrumbs
- Sort files using the sort dropdown (Name, Modified, Size, Owner)
- Toggle between Grid and List view using the view buttons
Auto-Refresh Behavior
The file list automatically refreshes after these operations:
- ✅ Creating a folder
- ✅ Uploading a file
- ✅ Moving a file or folder
- ✅ Copying a file or folder
- ✅ Starring or unstarring an item
- ✅ Deleting an item
- ✅ Restoring an item from bin
Manual refresh is not required after these operations.
Responsive Behavior
| Viewport | Layout | Notes |
|---|---|---|
| Desktop (1440px+) | Full file list with owner, size, date columns | All columns visible |
| Tablet (768px-1439px) | Condensed list, owner hidden | Owner column hidden |
| Mobile (<768px) | Grid view only, essential actions | Icon-based, swipe for actions |
Upload And Download
File Upload
Single File Upload
- Click Upload Files button (or drag file onto browser)
- Select one or more files from the file picker
- Upload progress shows in the Upload Queue panel (bottom-right)
- File appears in the file list when upload completes
Folder Upload (Desktop Only)
- Click Upload Folder button (hidden on mobile)
- Select a folder from the file picker
- Entire folder structure is recreated in the workspace
- Progress shows for each file in the queue
Large File Support (Multipart Upload)
Files over 100MB automatically use multipart upload:
| File Size | Chunk Size | Parallel Uploads |
|---|---|---|
| 100MB - 1GB | 5MB chunks | Up to 3 concurrent |
| 1GB - 5GB | 10MB chunks | Up to 5 concurrent |
| 5GB+ | 20MB chunks | Up to 5 concurrent |
Progress Tracking:
- Individual chunk progress shown
- Overall file progress percentage
- Upload can be cancelled mid-progress
- Failed chunks retry automatically
Upload Queue Panel
The Upload Queue appears in the bottom-right corner and shows:
- File name and size
- Individual progress bar per file
- Overall upload status (uploading, paused, complete, failed)
- Cancel button per file
- Retry button for failed uploads
File Download
- Right-click on the file OR click the action menu (•••)
- Select Download
- Backend generates a short-lived signed URL (expires in 15 minutes)
- Browser redirects to download the file directly from storage
Note: If download is unavailable, your role may lack Download permission. Contact a workspace admin.
Folders
Create Folder
- Click New Folder button
- Enter folder name in the dialog
- Click Create (or press Enter)
- Folder appears in the current directory
Naming Rules:
- Folder names cannot contain:
/ \ : * ? " < > | - Maximum length: 255 characters
- Names are case-sensitive (but displayed case-insensitively for search)
Folder Actions
| Action | Permission Required | Description |
|---|---|---|
| Open | Read | Navigate into folder |
| Rename | Update | Change folder name |
| Move | Update | Relocate to another folder |
| Copy | Create | Duplicate to another folder |
| Share | Update | Create public share link |
| Star/Unstar | Update | Mark as favorite |
| Delete | Delete | Move to bin |
| Restore | Delete | Recover from bin |
Folder Navigation
- Double-click folder to enter
- Breadcrumb click to go up levels
- Back arrow to return to previous folder (if available)
Sharing
Create Public Share Link
- Select a file or folder
- Click Share from the action menu
- Configure link options:
- Expiry: Set date when link stops working (optional)
- Password: Require password to access (optional)
- Download limits: Max number of downloads (optional)
- Click Create Link
- Copy the generated URL
Share Link URL Format
https://{workspace}.burdenoff.com/files/share/{token}
Example:
https://vibecontrols.burdenoff.com/files/share/abc123xyz789
Share Token Security
⚠️ Important:
- Share tokens are secret and should not be posted publicly
- Anyone with the token can access the shared item
- Use password protection for sensitive files
- Set expiry dates for time-limited sharing
Access Shared Files (Guest Mode)
Guests access shared files via the share token URL:
- No workspace login required
- Password-protected links prompt for password first
- Download limits shown if configured
- Guest access does not require workspace account
Revoke Share Link
- Navigate to the file/folder's share settings
- Click Revoke on the active link
- Link immediately stops working
Permissions
Permission Types
| Permission | Actions Allowed |
|---|---|
| Read | View, preview, download |
| Create | Upload files, create folders |
| Update | Rename, move, star, share |
| Delete | Move to bin, permanent delete |
| Admin | Manage permissions, configure settings |
Permission Inheritance
- Folders can have their own permission settings
- Files inherit folder permissions by default
- Explicit file permissions override folder permissions
Viewing Your Permissions
Item actions are dynamically shown based on your permissions. If you don't see certain options, you likely lack the required permission level.
Bin And Restore
How Deletion Works
- Soft Delete (Move to Bin):
- File/folder is marked as deleted in database
- Original location is preserved for restore
- Storage object remains until permanent delete
- Permanent Delete:
- Database record is removed
- Storage object is deleted
- Cannot be undone
Restore from Bin
- Navigate to Bin tab
- Find the item you want to restore
- Click Restore
- Item returns to its original location
Bin Retention
- Items in bin retain for 30 days (configurable by admin)
- After retention period, items are automatically permanently deleted
- Permanent delete is immediate and irreversible
Empty Bin
Workspace admins can Empty Bin to permanently delete all items. This action requires confirmation.
Search
Basic Search
- Click the search bar in the browser header
- Type file or folder name
- Results filter in real-time
Advanced Filters
Available filters (shown after entering search):
| Filter | Description |
|---|---|
| File type | Documents, Images, Videos, Audio, Archives |
| Date modified | Today, This week, This month, Custom range |
| Owner | Filter by uploader |
| Size | Small (<1MB), Medium (1-100MB), Large (>100MB) |
Search Scope
- Search is scoped to the current workspace
- Search does not cross workspace boundaries
- Partial name matches are supported
Limits and Quotas
List Limits
| Limit Type | Value | Notes |
|---|---|---|
| Page size | 100 items max | Backend enforces |
| Search results | 100 items max | Capped for performance |
| Deep folder nesting | 10 levels max | Root + 10 children |
Storage Quotas
Workspace storage is enforced at upload time:
- Upload fails if it would exceed workspace quota
- Quota is shared across all workspace members
- Admins can view quota usage in workspace settings
Large File Handling
| Aspect | Limit |
|---|---|
| Max single file size | 5GB |
| Max multipart chunks | 250 per file |
| Upload timeout | 1 hour per chunk |
| Signed URL validity | 15 minutes |
Troubleshooting
Upload Fails
| Cause | Solution |
|---|---|
| Exceeds workspace quota | Delete files or contact admin to increase quota |
| Network interruption | Retry upload; multipart resumes automatically |
| Invalid file type | Check with admin for allowed file types |
| File too large | Split into smaller files or archive |
Download Unavailable
| Cause | Solution |
|---|---|
| No download permission | Contact file owner or admin |
| Share link expired | Request new link from owner |
| File in bin | Restore from bin first |
Search Not Finding Files
| Cause | Solution |
|---|---|
| Misspelled name | Try partial name or use wildcards |
| Wrong workspace | Switch to the correct workspace |
| File not yet indexed | Wait for background indexing |
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
N | New Folder |
U | Upload Files |
/ | Focus search |
Esc | Clear search / Close dialog |
↑ ↓ | Navigate file list |
Enter | Open selected item |
Del | Delete selected item |
S | Star/Unstar selected item |
E | Share selected item |
Feature Flags
Some features require workspace-level feature flags:
| Feature | Flag Name |
|---|---|
| Starred tab | files.starred |
| Bin tab | files.bin |
| Folder upload | files.folderUpload |
| Share with expiration | files.shareExpiry |
| Password-protected shares | files.sharePassword |
| Advanced search | files.advancedSearch |
Contact a workspace admin to enable feature flags.
Related Documentation
- Upload Flow Sequence
- Download Flow Sequence
- Share Link Flow Sequence
- Permission Model
- RBAC Configuration (see RBAC overview)