> For the complete documentation index, see [llms.txt](https://academy.shade.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.shade.inc/shadefs/introduction-to-shadefs.md). # Introduction to ShadeFS ## **Overview** ShadeFS is a cloud drive mounting solution that completely changes how you interact with cloud-stored media files. Unlike traditional cloud storage solutions that require complete file downloads before access (ahem Dropbox), ShadeFS streams the segments you need in real-time, similar to how YouTube delivers video content. This approach give you immediate access to your media while optimizing bandwidth usage. ## **Key Features** * ShadeFS turns your cloud drive into a local folder accessible by default via the “/Volumes” folder * When you mount a drive, it appears in your local file system just like a physical hard drive, but with the added advantage of intelligent streaming and caching * The system automatically synchronizes file trees across all users, ensuring everyone on your team works with the same content structure regardless of their location. * Uploaded files are automatically pushed through our proxy generation and AI analysis pipelines ## **System Requirements** ShadeFS has a few requirements to get working optimally on your machine. * For working with 4K video content, we recommend a minimum internet speed of 500Mbps down * Users with lower bandwidth should consider working with proxy files or sub-4K resolution content * Your device should also have sufficient storage space for the cache, with a minimum of 10GB for basic operations ## **Getting Started** Once you have the desktop app downloaded and opened, you can mount any drive by navigating to it in the left panel, clicking the "..." menu, and selecting "Mount Drive." The drive will appear in your local file explorer, whether you're using Windows, macOS, or Linux. {% embed url="" %} ## **Mount Location** By default, each drive mounts in your operating system's standard location. Workspace owners and admins can set a custom mount location per drive in the drive's settings under **General > Custom Mount Path**, using the **macOS path**, **Linux path**, and **Windows path** fields. On Windows, you can mount a drive to a drive letter such as `X:` or `Z:` (the system drives C:, D:, and E: aren't allowed). Leave a field empty to use the system default. ## **Mount Backend (macOS)** On macOS, ShadeFS mounts drives through a file server built into the Shade desktop app, so you don't need to install anything extra. The server runs only on your Mac, and mounted drives appear under `/Volumes` like any other drive. If you prefer macFUSE, install it and turn on **Use macFUSE backend** in **Settings > ShadeFS > Configuration**. Only one drive can be mounted at a time with the macFUSE backend, and ShadeFS restarts when you toggle this setting. ## **Cache Configuration** ShadeFS uses a caching system to optimize performance for your media files. By default, the system creates a cache of 26GB in the **.shade** folder located in your user root directory. However, you can customize both the cache location and size in **Settings > ShadeFS > Cache Management** to better suit your needs. [Managing the ShadeFS Cache](https://academy.shade.inc/shadefs/managing-the-shadefs-cache) ## **Cache Directory** To modify your cache directory, open **Settings > ShadeFS > Cache Management** in the desktop app and click the **ShadeFS cache directory** field (on desktop app version 2.3.21 and earlier, this setting is under **Settings > ShadeFS > Configuration**). Here you can select any folder on your computer or an external drive as your cache location. We particularly recommend using a high-speed external SSD, such as a Samsung T7, for optimal performance. The cache location must be on a drive formatted as APFS (macOS), NTFS or ReFS (Windows), or ext4, XFS, or Btrfs (Linux). Drives formatted as exFAT or Mac OS Extended (HFS+) can't be used for the cache. ## **ShadeFS Usage Guidelines** ## **Permissions** ShadeFS access and mounting capabilities is restricted to workspace contractors, members, and administrators. When multiple users mount the same drive, they all see an identical file tree, which facilitates seamless collaboration across remote teams. ## **Uploads** For large-scale uploads exceeding 1000 assets or 100GB, we recommend using the webapp or desktop application rather than uploading through the mounted drive. We have optimized uploading through the app interface for large files. Any upload method you choose will automatically make content visible in both the webapp and desktop application, triggering our automatic proxy generation and AI processing systems. Files can be moved between drives by first mounting multiple drives and then moving files through your computer's file explorer between the drives ## **Offline Access** ShadeFS provides offline access capabilities through **pinning**. To access specific files or folders with weak internet connection (or none at all), simply right-click on the files/folders in the app and select "Pin to Cache." This action downloads a complete copy of the selected content to your local cache, making them fully accessible even if you are offline. You can view files that you have pinned via the **Pinned Items** page. See more at [Pinning Files Offline](https://academy.shade.inc/shadefs/pinning-files-offline). ## **Performance Optimization** There’s a few ways to maximize the performance for ShadeFS. * Use an external SSD for cache storage to significantly improve access speeds and overall system responsiveness * We recommend configuring your cache size based on your typical working set to ensure frequently accessed files remain readily available * While ShadeFS is designed to work efficiently with available bandwidth, try to maintain a stable internet connection while you use the mount * For users working with high-resolution content on limited bandwidth, we recommend making proxy files ## **Integration with Shade Ecosystem** Unlike other file streaming tools, ShadeFS is deeply integrated with the webapp and desktop app. When you upload files through a mounted drive, they are automatically indexed in the Shade system, which are immediately visible across web and desktop applications. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://academy.shade.inc/shadefs/introduction-to-shadefs.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.