Run locally

Relayfile runs as a lightweight background daemon. That's where OAuth tokens stay warm, provider rate limits are absorbed, webhook deliveries are deduplicated, and events fan out to all subscribed agents. It's an integration runtime — the same reason you run a database process rather than re-implementing storage per request. If you'd rather not run it, Relayfile Cloud runs the daemon for you.

Start the Docker stack

The fastest local path brings up the file server, the dev token issuer, and a seed step that creates a sample workspace:

cd docker
docker compose up --build

This starts three services:

Call the API over curl

The seed step prints a dev token to its logs. Pull it out, then read the tree and a file:

TOKEN="$(docker compose logs seed | awk '/token/ {print $NF}' | tail -1)"

curl -H "Authorization: Bearer $TOKEN" \
  -H "X-Correlation-Id: quickstart-tree" \
  "http://localhost:9090/v1/workspaces/ws_demo/fs/tree?path=/"

curl -H "Authorization: Bearer $TOKEN" \
  -H "X-Correlation-Id: quickstart-read" \
  "http://localhost:9090/v1/workspaces/ws_demo/fs/file?path=/docs/welcome.md"

X-Correlation-Id is required on authenticated requests. The full endpoint set is in the API reference.

Mount the workspace

Mount ws_demo as ordinary local files with the relayfile-mount daemon:

cd ..
RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
  --base-url http://localhost:9090 \
  --workspace ws_demo \
  --local-dir ./relayfile-mount

Now any local tool or agent can use ./relayfile-mount like a normal directory.

Scope the mount to subtrees

On large workspaces you don't want to pull the whole tree. Limit the daemon to one or more remote subtrees by repeating --remote-path. Each subtree is mirrored under the matching path inside --local-dir, which avoids full-workspace export pulls:

RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
  --base-url http://localhost:9090 \
  --workspace ws_demo \
  --local-dir ./relayfile-mount \
  --remote-path /github \
  --remote-path /slack/channels/proj-cloud

For long path lists, pass --paths-file ./paths.json. The file may be a JSON array of remote roots or a newline-separated list. Combine with --lazy-repos (see Mount layout) for huge-org GitHub workspaces.

Tune the FUSE caches

The FUSE layer caches file content in kernel memory independently of its attribute TTL. By default content is held for 30 seconds and attributes for 2 seconds. Tune content caching with --fuse-content-ttl (or the RELAYFILE_MOUNT_FUSE_CONTENT_TTL env var) when your workload needs fresher reads or can tolerate a longer cache window:

# 10-second content cache — reduces kernel re-reads for stable workspaces
RELAYFILE_TOKEN="$TOKEN" go run ./cmd/relayfile-mount \
  --workspace ws_demo \
  --local-dir ./relayfile-mount \
  --fuse-content-ttl 10s

This kernel content cache is independent of the SDK's client-side read cache — they operate at different layers and are tuned separately.