@relayfile/sdk

TypeScript SDK for relayfile — real-time filesystem for humans and agents.

Install

npm install @relayfile/sdk

Agent Workspace — Golden Path

The recommended way to use @relayfile/sdk in an agent workflow is through RelayfileSetup. This handles workspace creation, Notion authorization, environment variable generation for relayfile-mount, and agent invites.

import { RelayfileSetup } from '@relayfile/sdk/cli'

const setup = await RelayfileSetup.login({
  onLoginUrl: (url) => console.log(`Sign in to Relayfile Cloud: ${url}`),
})

// Create or resume a workspace
const workspace = await setup.createWorkspace({
  name: 'notion-research-room',
  agentName: 'lead-agent',
})

// Connect Notion — returns a link for the human to open
const notion = await workspace.connectNotion()
if (notion.connectLink) {
  console.log(`Connect Notion: ${notion.connectLink}`)
  await workspace.waitForNotion({ timeoutMs: 5 * 60_000 })
}

// Env vars for relayfile-mount (local dir or cloud sandbox)
const mountEnv = workspace.mountEnv({
  localDir: '/workspace/notion',
  remotePath: '/notion',
})

// Secret invite payload for a trusted co-worker agent — same scopes as this
// workspace's token (no per-invite downscoping).
const invite = workspace.agentInvite({ agentName: 'review-agent' })

// To grant a strictly narrower set of scopes, mint a fresh JWT via the cloud
// API. The cloud rejects requests that exceed the calling token's grant.
const scopedInvite = await workspace.agentInviteScoped({
  agentName: 'notion-summarizer',
  scopes: ['relayfile:fs:read:/notion/pages/*'],
})
// Never log invites — they contain credential material

For the full end-to-end journey, failure modes, and acceptance criteria see docs/agent-workspace-golden-path.md.

Run the demo locally:

npm run demo:agent-workspace --workspace=packages/sdk/typescript

The demo defaults to in-process mock cloud and relayfile servers, seeds a /notion file, mounts it through the deterministic harness, and proves read-only invited-agent behavior without requiring real Notion, Relaycast, or cloud credentials. For a real deployment, use RelayfileSetup.login() to send the human one Cloud sign-in URL, or use RelayfileSetup.fromCloudTokens() with previously persisted Cloud tokens. You can still pass accessToken directly to new RelayfileSetup() in CI or advanced hosts that already provide a valid Cloud bearer token. After Cloud auth, complete the Notion OAuth flow as described in docs/agent-workspace-golden-path.md.

The default @relayfile/sdk entry point is safe for Worker-style bundles and does not statically import the CLI-only mount launcher or local browser login helpers. Import interactive login and local mount launcher utilities from @relayfile/sdk/cli, @relayfile/sdk/cloud-login, or @relayfile/sdk/mount-launcher.

Low-Level Client Example

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

const client = new RelayFileClient({
  baseUrl: "https://api.relayfile.com",
  token: process.env.RELAYFILE_TOKEN ?? "",
  changeLog: {
    retentionMs: 7 * 24 * 60 * 60 * 1000,
    maxEntries: 10_000
  }
});

const workspaceId = "workspace_123";

const tree = await client.listTree(workspaceId, {
  path: "/",
  depth: 2
});

console.log(tree.entries.map((entry) => entry.path));

const file = await client.readFile(workspaceId, "/notes/todo.md");

console.log(file.content);

await client.writeFile({
  workspaceId,
  path: "/notes/todo.md",
  baseRevision: file.revision,
  content: `${file.content}\n- Follow up with SDK publish`,
  contentType: "text/markdown"
});

Use a relayfile JWT whose claims include workspace_id, agent_name, and aud: ["relayfile"]. The SDK adds X-Correlation-Id automatically for API calls.

The optional changeLog block configures the SDK's local per-workspace retained-change mirror used by subscribe(), open({ replayOnStart }), and getResourceAtEvent(eventId). Durable retention still lives on the Relayfile backend.

Full Docs

Full documentation is available in the relayfile docs.