From 48d744a585f7c737b870eccbdf095a036375f024 Mon Sep 17 00:00:00 2001 From: Khaliq Date: Sun, 23 Aug 2026 13:03:38 +0200 Subject: [PATCH 1/2] docs(relayfile): document one-command onboarding --- web/content/docs/file/agents.mdx | 2 +- web/content/docs/file/cli.mdx | 10 ++++++++-- web/content/docs/file/cloud.mdx | 16 +++++++--------- web/content/docs/file/quickstart.mdx | 27 +++++++++++++++++---------- 4 files changed, 33 insertions(+), 22 deletions(-) diff --git a/web/content/docs/file/agents.mdx b/web/content/docs/file/agents.mdx index 764dd5a..79b33bf 100644 --- a/web/content/docs/file/agents.mdx +++ b/web/content/docs/file/agents.mdx @@ -91,7 +91,7 @@ Honest answer: for **1 provider × 1 agent × one-shot action**, a dedicated pro ## Credentials -Two sources, in order: env overrides for CI (`CLOUD_API_URL`, `CLOUD_API_ACCESS_TOKEN`, `CLOUD_WORKSPACE_ID`), then `~/.agentworkforce/relay/cloud-auth.json` written by `agent-relay cloud login`. One login per machine; per-app permissions live in Cloud. +Two sources, in order: env overrides for CI (`CLOUD_API_URL`, `CLOUD_API_ACCESS_TOKEN`, `CLOUD_WORKSPACE_ID`), then `~/.agentworkforce/relay/cloud-auth.json` written by `npx relayfile@latest` or `agent-relay cloud login`. One shared login per machine; per-app permissions live in Cloud. diff --git a/web/content/docs/file/cli.mdx b/web/content/docs/file/cli.mdx index 6104b5b..5f37bdc 100644 --- a/web/content/docs/file/cli.mdx +++ b/web/content/docs/file/cli.mdx @@ -14,7 +14,7 @@ The CLI resolves a token in priority order, first match wins: 3. the canonical relay cloud session (cloud-hosted interactive use) 4. `~/.relayfile/credentials.json` (self-hosted / API-key compatibility) -For the cloud-hosted path, login is owned by the `agent-relay` CLI: `agent-relay login`, then `agent-relay workspace switch `, then any `relayfile` command. For self-hosted servers, use the API-key path: +The clean-machine Cloud path is simply `npx relayfile@latest`. Setup establishes the canonical shared Cloud session itself when one does not exist; other Agent Relay tools can reuse it. For self-hosted servers, use the API-key path: ```bash relayfile login --api-key --server https://api.relayfile.dev @@ -24,7 +24,13 @@ If no token is found, the CLI prints: `Error: not authenticated. Run 'agent-rela ## `relayfile setup` -The low-friction Cloud setup path for humans and agent-guided onboarding. It ensures you're logged in, creates or joins a Cloud workspace, requests a hosted connect session for the chosen provider, waits until it reports ready, and starts the mount loop. +The low-friction Cloud setup path for humans and agent-guided onboarding. With no arguments, it signs the user up, names the workspace after the current directory, selects GitHub, mounts at `./relayfile-mount`, and starts the sync loop: + +```bash +npx relayfile@latest +``` + +No invite code, copied token, prior account, or separately installed `agent-relay` CLI is required. Use the explicit form for another provider or workspace: ```bash relayfile setup --provider notion --workspace my-project --local-dir ./relayfile-mount diff --git a/web/content/docs/file/cloud.mdx b/web/content/docs/file/cloud.mdx index 50dff85..e150b1d 100644 --- a/web/content/docs/file/cloud.mdx +++ b/web/content/docs/file/cloud.mdx @@ -1,23 +1,21 @@ --- title: 'Relayfile Cloud' -description: 'Hosted Agent Relay runs the workspace, scoped auth, Nango OAuth, sync workers, and writeback workers — connect provider-backed files with one token.' +description: 'Hosted Agent Relay runs the workspace, scoped auth, Nango OAuth, sync workers, and writeback workers — connect provider-backed files with one command.' --- -If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running any infrastructure, use Hosted Agent Relay. Agent Relay Cloud runs the workspace, the Relayfile API, scoped auth, Nango OAuth, provider sync workers, and writeback workers for you. Your agents connect with a single token; there's no integration runtime on your machine. +If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running any infrastructure, use Hosted Agent Relay. Agent Relay Cloud runs the workspace, the Relayfile API, scoped auth, Nango OAuth, provider sync workers, and writeback workers for you. There is no integration runtime or token configuration on your machine. ## The setup flow -`relayfile setup` is the human and agent-guided entry point. It connects to `agentrelay.com`, creates or joins a cloud workspace, completes provider auth, waits for sync, and mounts the resulting files: +From the project where your agent will work: ```bash -relayfile setup \ - --provider notion \ - --workspace my-agent \ - --local-dir ./relayfile-mount \ - --no-open +npx relayfile@latest ``` -`--no-open` prints the hosted login and connect URLs instead of opening a browser, which is what you want inside agents and headless environments. The local directory is just the agent's file interface — the integration stack is hosted. Re-running with the same workspace name reuses the workspace, refreshes the session, and only opens a new connect flow when the requested provider isn't already connected. +Relayfile completes Google sign-in, automatically creates the account and workspace without an invite code, connects GitHub, and mounts at `./relayfile-mount`. The local directory is just the agent's file interface — the integration stack is hosted. Re-running the same command reuses the workspace, refreshes the session, and skips provider connection when GitHub is already connected. + +Use `npx relayfile@latest setup --provider notion --workspace my-agent --local-dir ./relayfile-mount` for another provider or explicit names. `--no-open` prints hosted login and connect URLs instead of opening a browser. After setup, hand the agent the mount path and it reads and writes under `$RELAYFILE_LOCAL_DIR//...` instead of calling provider APIs directly: diff --git a/web/content/docs/file/quickstart.mdx b/web/content/docs/file/quickstart.mdx index f5606e1..4588a98 100644 --- a/web/content/docs/file/quickstart.mdx +++ b/web/content/docs/file/quickstart.mdx @@ -3,7 +3,7 @@ title: 'Quickstart' description: 'The fastest path to a working Relayfile mount: hosted with one command, then read and write provider files.' --- -The fastest path is **hosted**: Agent Relay runs the integration stack for you — OAuth, sync workers, writeback — so you only run a local mount. One command and you have provider-backed files in an ordinary directory. +The fastest path is **hosted**: Agent Relay runs the integration stack for you — OAuth, sync workers, writeback — so you only run a local mount. One command signs you up and puts provider-backed files in an ordinary directory. Want to run the whole stack yourself instead? See [Run locally](/docs/file/run-locally) for the self-hosted Docker path. The source lives at [github.com/AgentWorkforce/relayfile](https://github.com/AgentWorkforce/relayfile) — clone it first. @@ -11,25 +11,32 @@ The fastest path is **hosted**: Agent Relay runs the integration stack for you ## One command -If you want Notion, Slack, Linear, GitHub, or other provider-backed files without running infrastructure, use Hosted Agent Relay. The CLI logs you in, creates or joins a cloud workspace, completes provider auth, waits for sync, and mounts the result. +From the project where your agent will work, run: ```bash -relayfile setup \ - --provider notion \ - --workspace my-agent \ - --local-dir ./relayfile-mount \ - --no-open +npx relayfile@latest ``` -`--no-open` prints the hosted login and connect URLs instead of opening a browser — useful inside agents and headless environments. The command connects to `agentrelay.com`, completes the Nango connect flow, blocks until the provider reports ready, and starts the mount sync loop. +Relayfile opens Google sign-in, creates your account and a workspace named after the current directory, connects GitHub, and mounts at `./relayfile-mount`. No invite code, API token, existing Cloud account, or separate `agent-relay` installation is required. -When it returns, `./relayfile-mount` is a live mirror of your workspace: +Keep that terminal open for synchronization. In another terminal, `./relayfile-mount` is the live mirror of your workspace: ```bash -ls ./relayfile-mount/notion +ls ./relayfile-mount/github cat ./relayfile-mount/LAYOUT.md ``` +For a different provider or explicit names, use: + +```bash +npx relayfile@latest setup \ + --provider notion \ + --workspace my-agent \ + --local-dir ./relayfile-mount +``` + +Add `--no-open` to print the hosted login and connect URLs instead of opening a browser, which is useful inside agents and headless environments. + See [Relayfile Cloud](/docs/file/cloud) for what the hosted plane manages, and [Mounting](/docs/file/mounting) to do the same thing programmatically from a sandbox. ## Read and write From cb7797696d8d20f1cdb69c350a6628d63ea0e23b Mon Sep 17 00:00:00 2001 From: Khaliq Date: Sun, 23 Aug 2026 13:15:09 +0200 Subject: [PATCH 2/2] docs(relayfile): clarify quickstart defaults --- web/content/docs/file/cli.mdx | 4 +++- web/content/docs/file/quickstart.mdx | 13 +++++++------ 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/web/content/docs/file/cli.mdx b/web/content/docs/file/cli.mdx index 5f37bdc..7e09779 100644 --- a/web/content/docs/file/cli.mdx +++ b/web/content/docs/file/cli.mdx @@ -33,9 +33,11 @@ npx relayfile@latest No invite code, copied token, prior account, or separately installed `agent-relay` CLI is required. Use the explicit form for another provider or workspace: ```bash -relayfile setup --provider notion --workspace my-project --local-dir ./relayfile-mount +npx relayfile@latest setup --provider notion --workspace my-project --local-dir ./relayfile-mount ``` +The bare command passes its GitHub/current-directory/`./relayfile-mount` values directly and does not prompt for them. The table below applies to an explicit `relayfile setup`: if one of its first three flags is omitted, the wizard prompts and offers the shown value where applicable. + | Flag | Default | Description | |---|---|---| | `--provider` | prompted (`github`) | Integration to connect; `none` to skip | diff --git a/web/content/docs/file/quickstart.mdx b/web/content/docs/file/quickstart.mdx index 4588a98..c528368 100644 --- a/web/content/docs/file/quickstart.mdx +++ b/web/content/docs/file/quickstart.mdx @@ -45,14 +45,15 @@ Once mounted, the interface is the filesystem you already know: ```bash # read -cat ./relayfile-mount/linear/issues/AGE-12__fix-login-bug.json +cat ./relayfile-mount/github/repos/acme/api/pulls/42/metadata.json -# patch back to the provider by writing the canonical path -echo '{"state":"In Review"}' \ - > ./relayfile-mount/linear/issues/AGE-12__fix-login-bug.json +# post a pull-request review by writing the canonical path +cat > ./relayfile-mount/github/repos/acme/api/pulls/42/reviews/review.json <<'EOF' +{"body":"Looks good to me.","event":"COMMENT"} +EOF -# find across providers -grep -rl '"state":"Todo"' ./relayfile-mount/linear/issues/ +# find pull requests across connected repositories +find ./relayfile-mount/github/repos -path '*/pulls/*/metadata.json' ``` See [Reads and writes](/docs/file/reads-and-writes) for the full PATCH / CREATE / DELETE model.