# Using Shared Cache

Shared Cache is an on-prem server that enables teams to securely share files that have been accessed by other team members within the same LAN.

As an example:

1. **Team Member 1** access `large_video.mp4` while connected to the shared cache
2. ShadeFS begins serving that file to **Team Member 1** from the cloud
3. In the background, the shared cache also begins caching `large_video.mp4`
4. The shared cache fully finishes caching `large_video.mp4`
5. **Team Member 2** now accesses `large_video.mp4` in ShadeFS
6. The shared cache runs permission checks to validate **Team Member 2** has access to `large_video.mp4`
7. `large_video.mp4` is immediately served at the maximum speed of the LAN from the shared cache

In this setup, the second access is both served at the maximum speed making playback largely instant and avoids using bandwidth against the cloud. Large shared cache instances can almost entirely avoid cloud round trips except for the first access.

## Download & Setup

Shared Cache is a terminal executable with no UI. You can get a version to download by asking us. The defaults are generally correct for most setups meaning for most people it's typically just a double click to launch.

## S3 Support

Shared Cache supports using both a local (disk) backend and an on prem S3 target for caching data. This can be enabled by passing `--storage-backend=s3` with the endpoint, bucket, region, access, and secret.

## Configuration Options

```bash
Usage: shared-cache [options]

Options:
  --port <number>                    Server port (default: 8003)
  --fs-ws-url <url>                  Upstream ShadeFS WebSocket URL (default: wss://fs.shade.inc)
  --fs-api-url <url>                 Upstream ShadeFS API URL (default: https://fs.shade.inc)
  --local-cache-location <path>            Cache storage directory (default: ./cache)
  --database-location <path>         SQLite database file path (default: ./shared_cache.db)
  --max-cache-size <bytes>           Maximum cache size in bytes (default: 500GB)
  --cache-check-interval <ms>        Cache cleanup interval in milliseconds (default: 300000)
  --storage-backend <type>           Storage backend: filesystem or s3 (default: filesystem)
  --discovery-server-name <name>     mDNS service name (default: Default Name)

  S3 Storage Options (when --storage-backend=s3):
  --s3-endpoint <url>                S3 endpoint URL
  --s3-bucket <name>                 S3 bucket name
  --s3-region <region>               S3 region
  --s3-access-key-id <key>           S3 access key ID
  --s3-secret-access-key <secret>    S3 secret access key
  --s3-path-prefix <prefix>          S3 key prefix (optional)

  Advanced Options:
  --download-worker-count <number>   Number of download workers (default: 5)
  --download-concurrent-chunks <n>   Concurrent chunks per worker (default: 4)
  --download-chunk-size <bytes>      Download chunk size (default: 128MB)
  --upload-concurrent-chunks <n>     Concurrent upload chunks (default: 4)
  --upload-chunk-size <bytes>        Upload chunk size (default: 64MB)
  --version, -v                      Show version information
  --help, -h                         Show this help message

Environment Variables:
  All options can also be set via environment variables using SCREAMING_SNAKE_CASE.
  Example: PORT, FS_WS_URL, CACHE_LOCATION, MAX_CACHE_SIZE_BYTES, etc.

Examples:
  ./shared-cache --port 8080 --local-cache-location /var/cache/shade
  ./shared-cache --storage-backend s3 --s3-bucket my-bucket --s3-region us-east-1
  PORT=8080 LOCAL_CACHE_LOCATION=/var/cache/shade ./shared-cache
```

## Joining the Shared Cache

Because the permissions are handled by the Shared Cache, joining is incredibly easy and requires no password. The shared cache advertises using bonjour. In most cases clients on the same network detect it and a modal will pop up asking if they would like to join.

If no modal appears, the cache can be joined directly by going to Settings → Shared Cache → Connect Manually and typing in the address. An example input might look like `http://192.168.1.45:8003`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.shade.inc/shared-cache/using-shared-cache.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.