/setting-up-relayfile

name: setting-up-relayfile
description: Use when an agent or human needs to set up relayfile end-to-end so agents can read and write provider files through a local mount. Covers `relayfile setup`, dynamic integration discovery with `relayfile integration available/search`, Nango and Composio backend selection, Atlassian site selection and metadata, cloud login, OAuth/connect flows, mount verification, `RELAYFILE_LOCAL_DIR` handoff, writeback status and retry commands, and key May 2026 cloud-mount gotchas.

Setting Up Relayfile (Mount + Writeback for Agents)

Overview

Relayfile mounts a provider (Notion, Linear, Slack, GitHub, and other adapter-backed integrations) as ordinary files on disk so an agent can read and write through the filesystem instead of calling APIs. This skill is the canonical setup recipe. Follow it top-to-bottom for first-time setup; jump to **Recovering from breakage** if a working mount has gone wrong.

When to use this skill

• An agent needs read access to a provider (e.g., "summarize this Notion database").
• An agent needs to write back to a provider (e.g., "post a review on this Notion page", "update this Linear issue").
• A human is setting up a mount before delegating work to an agent.
• A mount stopped reflecting changes and you need to diagnose where.

What you get

After setup, files appear under `<local-dir>/<provider>/...`:

~/relayfile-mount/notion/
├── databases/
│   ├── <slug>--<id>/
│   │   ├── metadata.json     ← database schema (read-only)
│   │   └── pages/
│   │       ├── <slug>--<id>.json     ← page metadata
│   │       └── <slug>--<id>/
│   │           ├── content.md        ← page body (READ + WRITE)
│   │           └── blocks/<id>.json  ← raw Notion block tree
└── pages/                            ← top-level pages (not in a database)

Read = `cat`. Write = overwrite, create, or remove files in writable adapter resource directories. The mount daemon picks up the change, queues a writeback, and the cloud delivers to the provider's API.

Current mounts are also self-describing. Start with `<local-dir>/LAYOUT.md`, then read provider-specific `<provider>/LAYOUT.md` files and nearby `_index.json` files instead of hard-coding paths from memory. Entity filenames may use a `<sanitized-name>__<id>` convention, and some providers expose alias views such as `by-title/`, `by-id/`, `by-name/`, or `by-state/`.

Prerequisites

• Recent `relayfile` CLI on `$PATH`. Verify: `relayfile --help` should list `setup`, `integration`, `writeback`, and the `integration available` / `integration search` / `integration set-metadata` subcommands.
• A modern macOS or Linux shell with `jq` for JSON inspection. AWS CLI access is optional and only needed for internal cloud log diagnostics.
• Network access to `agentrelay.com/cloud` (cloud control plane), `api.relayfile.dev` (relayfile API), `connect.nango.dev` (Nango OAuth), and Composio connect endpoints when using `--backend composio`.

Step 1 — Run setup (interactive happy path)

relayfile setup \
  --provider notion \
  --workspace my-agent \
  --local-dir ~/relayfile-mount \
  --no-open

What this does, in order:

1. **Cloud login.** Opens a localhost callback server, prints a URL to `agentrelay.com/cloud/api/v1/cli/login?...`. You complete the login in the browser; the cloud redirects back to `127.0.0.1:<port>/callback` with an access token. The CLI stores cloud credentials in `~/.relayfile/cloud-credentials.json` and the active Relayfile workspace token in `~/.relayfile/credentials.json`. 2. **Workspace create.** POSTs `/api/v1/workspaces` with `{"name": "my-agent"}`. Returns `{ workspaceId: "rw_<8hex>", relaycastApiKey, relayfileUrl, ... }`. The workspace ID is the prefix-style `rw_*` format — not a UUID. 3. **Integration connect.** By default, mints a Nango Connect URL like `https://connect.nango.dev/?session_token=nango_connect_session_<hash>` and opens it (or prints it, with `--no-open`). With `--backend composio`, the cloud resolves the provider to a Composio toolkit, finds or creates the Composio auth config when Composio supports automatic managed auth, and mints a Composio connect URL. You complete the provider auth there. The provider callback inserts a row into `workspace_integrations` and queues an initial sync. For Jira and Confluence, the CLI then lists the Atlassian sites covered by the OAuth grant and asks which site to bind when more than one is available. 4. **Initial sync.** The cloud nango-sync-worker pulls page metadata + content from the provider and writes it to relayfile. Takes ~30s for a small workspace. 5. **Mount.** Starts a local daemon that polls `api.relayfile.dev/v1/workspaces/<id>/sync/status` every 30s and reflects changes into `<local-dir>/<provider>/`.

**Use `--no-open` if you're an agent**: the wizard otherwise tries to open a browser, which usually fails in headless environments and burns the OAuth state.

Step 2 — Verify the mount is healthy

relayfile status my-agent

Healthy output:

workspace rw_xxxxxxxx (my-agent)   mode: poll   lag: 4s

local mirror: /Users/you/relayfile-mount
daemon: running (pid 12345)

  notion       ready    214 files    last event 2s ago

pending writebacks: 0    failed: 0    dead-lettered: 0

What each row means:

• `lag: <N>s` — how stale the mirror is relative to the cloud. >60s means investigate.
• `daemon: not running` — the mount poller exited. Start it with `relayfile mount my-agent ~/relayfile-mount &`.
• `pending writebacks` — local writes queued for upload. Should drain to 0 within ~30s.
• `failed` — lifetime counter of non-2xx responses from the cloud's PUT endpoint. **Informational; don't gate on this.**
• `dead-lettered` — count of writebacks that exhausted retries and got persisted under `<local-dir>/.relay/dead-letter/<opId>.json`. **Gate on this.**

If `dead-lettered > 0`, see **Recovering from breakage** below.

Step 3 — Hand off to an agent

Two patterns, dep