> 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/shared-cache/using-shared-cache.md).

# 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

Options are passed as `--option value`. Unrecognized options are ignored without an error, so check the settings Shared Cache prints when it starts to confirm your values took effect.

```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 <bytes>           Maximum cache size in bytes (default: 500GB)
  --cache-check-interval-ms <ms>           Cache cleanup interval in milliseconds (default: 300000)
  --storage-backend <type>                 Storage backend: local or s3 (default: local)
  --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)
  --s3-url-expiry-seconds <seconds>        Presigned URL expiry (default: 86400)

  Advanced Options:
  --download-worker-concurrent-chunks <n>  Concurrent chunks per download worker (default: 10)
  --download-worker-chunk-size <bytes>     Download chunk size in bytes (default: 128MB)
  --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, LOCAL_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`

## Shared Cache not working?

If Shared Cache isn't working or you don't see other devices on your network:

1. Open System Settings → Privacy & Security → Local Network.
2. Make sure Shade is enabled.
3. If it was disabled, enable it and restart Shade before trying again.


---

# 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/shared-cache/using-shared-cache.md?ask=<question>&goal=<user_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.