Skip to main content

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.


Browser Layout​

The Files browser is organized into these key areas:

AreaDescription
HeaderSearch bar, view toggles (grid/list), sort options
Tab BarAll Files, Recent, Starred, Bin tabs (feature-gated)
BreadcrumbShows current folder path; click to navigate up
File ListGrid or list view of files and folders
Action BarUpload Files, Upload Folder, New Folder buttons

Tab Navigation​

TabPurposeAccess
All FilesBrowse all files in current folderAll workspace members
RecentFiles and folders updated in the last 30 daysAll workspace members
StarredFiles and folders marked as favoriteRequires files.starred feature flag
BinSoft-deleted items pending permanent delete or restoreRequires files.bin feature flag

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​

  1. Click All Files in the tab bar
  2. Navigate folders by clicking folder names or using breadcrumbs
  3. Sort files using the sort dropdown (Name, Modified, Size, Owner)
  4. 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​

ViewportLayoutNotes
Desktop (1440px+)Full file list with owner, size, date columnsAll columns visible
Tablet (768px-1439px)Condensed list, owner hiddenOwner column hidden
Mobile (<768px)Grid view only, essential actionsIcon-based, swipe for actions

Upload And Download​

File Upload​

Single File Upload​

  1. Click Upload Files button (or drag file onto browser)
  2. Select one or more files from the file picker
  3. Upload progress shows in the Upload Queue panel (bottom-right)
  4. File appears in the file list when upload completes

Folder Upload (Desktop Only)​

  1. Click Upload Folder button (hidden on mobile)
  2. Select a folder from the file picker
  3. Entire folder structure is recreated in the workspace
  4. Progress shows for each file in the queue

Large File Support (Multipart Upload)​

Files over 100MB automatically use multipart upload:

File SizeChunk SizeParallel Uploads
100MB - 1GB5MB chunksUp to 3 concurrent
1GB - 5GB10MB chunksUp to 5 concurrent
5GB+20MB chunksUp 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​

  1. Right-click on the file OR click the action menu (•••)
  2. Select Download
  3. Backend generates a short-lived signed URL (expires in 15 minutes)
  4. 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​

  1. Click New Folder button
  2. Enter folder name in the dialog
  3. Click Create (or press Enter)
  4. 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​

ActionPermission RequiredDescription
OpenReadNavigate into folder
RenameUpdateChange folder name
MoveUpdateRelocate to another folder
CopyCreateDuplicate to another folder
ShareUpdateCreate public share link
Star/UnstarUpdateMark as favorite
DeleteDeleteMove to bin
RestoreDeleteRecover 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​

  1. Select a file or folder
  2. Click Share from the action menu
  3. Configure link options:
  • Expiry: Set date when link stops working (optional)
  • Password: Require password to access (optional)
  • Download limits: Max number of downloads (optional)
  1. Click Create Link
  2. Copy the generated URL
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
  1. Navigate to the file/folder's share settings
  2. Click Revoke on the active link
  3. Link immediately stops working

Permissions​

Permission Types​

PermissionActions Allowed
ReadView, preview, download
CreateUpload files, create folders
UpdateRename, move, star, share
DeleteMove to bin, permanent delete
AdminManage 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​

  1. 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
  1. Permanent Delete:
  • Database record is removed
  • Storage object is deleted
  • Cannot be undone

Restore from Bin​

  1. Navigate to Bin tab
  2. Find the item you want to restore
  3. Click Restore
  4. 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.


  1. Click the search bar in the browser header
  2. Type file or folder name
  3. Results filter in real-time

Advanced Filters​

Available filters (shown after entering search):

FilterDescription
File typeDocuments, Images, Videos, Audio, Archives
Date modifiedToday, This week, This month, Custom range
OwnerFilter by uploader
SizeSmall (<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 TypeValueNotes
Page size100 items maxBackend enforces
Search results100 items maxCapped for performance
Deep folder nesting10 levels maxRoot + 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​

AspectLimit
Max single file size5GB
Max multipart chunks250 per file
Upload timeout1 hour per chunk
Signed URL validity15 minutes

Troubleshooting​

Upload Fails​

CauseSolution
Exceeds workspace quotaDelete files or contact admin to increase quota
Network interruptionRetry upload; multipart resumes automatically
Invalid file typeCheck with admin for allowed file types
File too largeSplit into smaller files or archive

Download Unavailable​

CauseSolution
No download permissionContact file owner or admin
Share link expiredRequest new link from owner
File in binRestore from bin first

Search Not Finding Files​

CauseSolution
Misspelled nameTry partial name or use wildcards
Wrong workspaceSwitch to the correct workspace
File not yet indexedWait for background indexing

Keyboard Shortcuts​

ShortcutAction
NNew Folder
UUpload Files
/Focus search
EscClear search / Close dialog
↑ ↓Navigate file list
EnterOpen selected item
DelDelete selected item
SStar/Unstar selected item
EShare selected item

Feature Flags​

Some features require workspace-level feature flags:

FeatureFlag Name
Starred tabfiles.starred
Bin tabfiles.bin
Folder uploadfiles.folderUpload
Share with expirationfiles.shareExpiry
Password-protected sharesfiles.sharePassword
Advanced searchfiles.advancedSearch

Contact a workspace admin to enable feature flags.


  • Upload Flow Sequence
  • Download Flow Sequence
  • Share Link Flow Sequence
  • Permission Model
  • RBAC Configuration (see RBAC overview)