# Setting Up Relayfile

Use when an agent or human needs to set up relayfile end-to-end so agents can read and...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill setting-up-relayfile -g -a gemini-cli -y`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

```text
~/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)
```

### 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)

#### ```bash

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.agents/skills/setting-up-relayfile/SKILL.md