Setting Up Relayfile

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 //...:

~/relayfile-mount/notion/
├── databases/
│   ├── --/
│   │   ├── metadata.json     ← database schema (read-only)
│   │   └── pages/
│   │       ├── --.json     ← page metadata
│   │       └── --/
│   │           ├── content.md        ← page body (READ + WRITE)
│   │           └── blocks/.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 /LAYOUT.md, then read provider-specific /.layout.md files and nearby _index.json files instead of hard-coding paths from memory. Entity filenames may use a __ 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:/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_", 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_ 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//sync/status every 30s and reflects changes into //.

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: 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 /.relay/dead-letter/.json. Gate on this.

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

Step 3 — Hand off to an agent

Two patterns, depending on where the agent runs:

Pattern A: local agent (Claude Code, scripts, Cursor)

The agent reads files directly:

export RELAYFILE_LOCAL_DIR=~/relayfile-mount
# point Claude Code at the dir or `cd` in

Mental model for the agent: ordinary files. Use Read, Write, Edit, Glob, Grep — same as any project directory. Writes propagate within ~30s.

Before writing, read the relevant _PERMISSIONS.md or discovery files for the target subtree. If a path is denied, Relayfile preserves the local copy and records the denial in /.relay/permissions-denied.log.

Pattern B: remote agent / SDK access (no disk mirror)

Use @relayfile/sdk against the workspace token:

import { RelayFileClient } from '@relayfile/sdk';

const token = process.env.RELAYFILE_TOKEN; // from ~/.relayfile/credentials.json
const client = new RelayFileClient({ token, server: 'https://api.relayfile.dev' });

// Read
const file = await client.getFile('rw_xxxxxxxx', '/notion/pages/xxx/content.md');

// Write — triggers writeback automatically
await client.putFile('rw_xxxxxxxx', '/notion/pages/xxx/content.md', {
  content: '# New body\n\n…',
  contentType: 'text/markdown',
});

The token issued by relayfile setup carries (as of May 2026): fs:read, fs:write, sync:read, sync:trigger, ops:read. The last two were added so agents can introspect the writeback pipeline (relayfile pull, relayfile ops list, GET /v1/workspaces//ops/).

Step 4 — Verify writeback works (optional but recommended)

Skip-able if the agent only reads. Required if the agent will write.

1. Pick a throwaway page in the provider.
2. Write a marker:

``bash echo "[writeback test $(date -u +%FT%TZ)]" > ~/relayfile-mount/notion/pages//content.md ``

1. Wait 30s.
2. Open the provider's web UI; the marker should appear.
3. Run relayfile writeback status — dead-lettered should still be 0.

If the marker doesn't appear in step 4, see Recovering from breakage.

Discover writeback contracts before writing

Do not guess writeback shapes and do not use a magic new.json filename. Current relayfile adapters ship discovery documents for writable resources:

A typical discovery surface looks like:

/
├── .adapter.md                         ← adapter overview, operations, ID patterns
└── /
    ├── .schema.json                    ← full-record JSON Schema, draft 2020-12
    └── .create.example.json            ← minimal create payload

• First check which writeback contract the mounted workspace exposes. Run find "$RELAYFILE_LOCAL_DIR" \( -name '.adapter.md' -o -name '.schema.json' -o -name 'new.json' \) | head -40. If discovery files are absent and new.json templates are present, the mounted workspace is still on the pre-file-native adapter bundle; do not apply the create-by-filename flow until the cloud/adapter deployment has refreshed that workspace.
• Read the provider .adapter.md first. In mounted workspaces this may appear under the provider tree or under /discovery//.adapter.md; if unsure, run find "$RELAYFILE_LOCAL_DIR" -path '*/.adapter.md'.
• Read the resource .schema.json before writing JSON. It is JSON Schema draft 2020-12 for the full synced record. Fields with "readOnly": true are server-managed and must not be written. Common schema paths are resource-local, such as /linear/issues/.schema.json; packaged adapters also carry a discovery copy under discovery//....
• For creates, start from the sibling .create.example.json. The create example intentionally omits read-only fields.
• For edits, write only mutable fields to a canonical .json; omitted fields are left alone.
• For creates, write a valid JSON document to any non-canonical filename in the resource directory, such as draft-message.json or create issue.json. The adapter creates the provider record at the real .json and rewrites the draft file as a receipt/pointer.
• For deletes, remove the canonical .json only when the resource's .adapter.md says delete is supported.

The ` pattern is resource-specific. A Linear issue ID is a UUID; a Slack message ID is a timestamp-like token; GitHub and many CRM IDs are integers. The .adapter.md` ID pattern section is the source of truth for whether a filename routes to PATCH/DELETE or CREATE.

Path conventions per provider

| Provider | Read paths | Write paths | | -------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Notion | /notion/pages/--/content.md, /notion/databases//pages/.../content.md, .json (metadata) | same paths overwrite the body / properties | | Slack | /slack/channels//messages/ plus .adapter.md / .schema.json discovery | create by writing a valid message JSON to /slack/channels//messages/.json; edit/delete canonical message files when supported | | Linear | /linear/issues/.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///pulls//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.

/.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

Use available when you want to browse or filter the catalog. Use search when you already have a term. --refresh bypasses the local catalog cache and is worth using when a provider was just added in Nango or Composio. Add --json when an agent needs machine-readable output.

Then connect the provider, optionally selecting the backend:

relayfile integration connect linear --workspace my-agent
relayfile integration connect slack  --workspace my-agent
relayfile integration connect dockerhub --backend composio --workspace my-agent --no-open
relayfile integration list           --workspace my-agent

For Jira and Confluence, a single Atlassian OAuth grant can cover multiple sites. After a fresh relayfile setup --provider jira|confluence or relayfile integration connect jira|confluence, the CLI calls Cloud's accessible-resources endpoint. If there is one site, it auto-selects it; if there are multiple sites, it prompts for a numbered choice before waiting for initial sync. The selected site's cloudId and baseUrl are saved as integration metadata so Cloud knows which tenant to sync.

If the picker was skipped, the wrong site was chosen, or an operator needs to update provider metadata later, use integration set-metadata. The command replaces the provider metadata namespace, so include every key you want to keep:

relayfile integration set-metadata jira \
  cloudId=abc-123 \
  baseUrl=https://example.atlassian.net \
  --workspace my-agent \
  --yes

set-metadata accepts flat KEY=VALUE pairs only. Keys such as site.cloudId or site[cloudId] are rejected locally; nested metadata is not part of the v1 CLI contract. Re-running relayfile integration connect jira or confluence for an already-connected provider should not overwrite existing metadata unless it starts a fresh OAuth connect.

Backend rules:

• Nango is the default backend for the standard Relayfile providers such as Notion, Linear, Slack, and GitHub.
• Composio can be requested explicitly with --backend composio for supported providers and dynamic Composio toolkits.
• User-facing aliases are allowed where the cloud knows them. For example, dockerhub resolves to the Composio toolkit slug docker_hub; if discovery shows docker_hub, either spelling is acceptable for connect.
• For Composio, the cloud first lists existing auth configs for the toolkit. If none exists, it attempts to create a managed/default auth config automatically. If Composio cannot create managed auth for that toolkit, the command returns an actionable error; at that point the human must add a custom auth config in Composio Authentication Management and retry the same relayfile integration connect ... command.

Each provider gets its own subtree under /. Disconnect with relayfile integration disconnect — leaves a marker at .relay/disconnected/.json and removes the provider's tree from the mirror.

Common gotchas

G1 — Cold-start 500 on workspace create

POST /api/v1/workspaces sometimes 500s on the first call after the cloud Lambda has been idle. Retry once before doing anything diagnostic. Verified May 2026: same call succeeded immediately on retry.

If it 500s twice in a row, check aws logs tail /aws/lambda/clou-production-AgentRelayCloudWebServerUseast1Function- --since 5m --follow for the actual stack trace.

G2 — OAuth callback timing trap

The wizard prints the cloud-login URL, opens a localhost callback server, then waits. If you complete the login after the wizard has timed out (or if you click the callback URL by hand later), the redirect-to-localhost won't load — that's expected. The login already completed; the wizard

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: AgentWorkforce
• Source: AgentWorkforce/relay
• License: Apache-2.0
• Homepage: https://agentrelay.com

Install and usage instructions live in the source repository linked above.