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.
Instrucciones de origen · Vista previa de solo lectura
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.
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>/...:
Recent relayfile CLI on $PATH. Verify: relayfile --help should list setup, , , and the / / subcommands.
integration
writeback
integration available
integration search
integration set-metadata
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.
/slack/channels/<id>/messages/ plus .adapter.md / .schema.json discovery
create by writing a valid message JSON to /slack/channels/<id>/messages/<non-canonical>.json; edit/delete canonical message files when supported
Linear
/linear/issues/<id>.json, comments under issue resources, plus .adapter.md / .schema.json discovery
create by writing a valid issue/comment JSON to a non-canonical filename; edit/delete canonical issue files when supported
GitHub
/github/repos/<owner>/<repo>/pulls/<n>/metadata.json, files.json, plus .adapter.md / .schema.json discovery
create a review by writing the review JSON to a non-canonical file under the reviews resource
new.json is not special in the file-native adapter contract. If a current .adapter.md and .schema.json are present, translate older examples using /messages/new.json or /comments/new.json to "write the create payload to any non-canonical filename in the resource directory." If the live mount only exposes new.json, treat that as an older deployment surface and follow the mounted template or wait for the workspace to refresh onto the new adapter version.
<local-dir>/.relay/ is reserved — never write there. Anything you put under it gets ignored or treated as daemon state.
Adding more integrations after setup
Do not guess provider names. Ask the CLI for the live catalog first; it pulls static Relayfile integrations plus dynamic Nango providers and Composio toolkits from the cloud, then caches the result locally.
relayfile integration available --refresh
relayfile integration search docker --backend composio --refresh
relayfile integration available --backend nango --search notion
When you're done with a mount and want to tear down:
# 1. stop the daemon
relayfile stop my-agent
# 2. disconnect each integration (revokes OAuth, removes <provider>/ tree)
relayfile integration disconnect notion --workspace my-agent --yes# 3. remove the local workspace registration
relayfile workspace delete my-agent --yes# 4. delete the mirror dirrm -rf ~/relayfile-mount
What this skill does NOT cover
Self-hosted relayfile (running your own relayfile-server Go binary against a private Nango). For most agent use-cases the managed cloud at agentrelay.com is the right choice; self-hosted is for environments where data residency rules out the cloud.
Multi-workspace agents. A single agent talking to multiple workspaces simultaneously needs careful token handling that's out of scope here.
GitHub-via-relayfile for source code. The GitHub adapter exists but the productized cloud-mount workflow is heavier-weight than git clone; only use it if the agent specifically benefits from filesystem-shaped access to PR metadata, reviews, etc.
