Workspace sync

An agent can back up its workspace — the files it works with and its saved sessions — to Alfe and restore them later, for example onto a fresh machine. These endpoints are what the agent’s built-in sync uses; you can call them directly with the @alfe.ai/agent-api-client.

File bytes move to and from storage over short-lived presigned URLs. The agent API hands you the URL; you PUT or GET the bytes directly.

Register

Register the agent for workspace sync (safe to call repeatedly).

sync.ts

const { agent } = await client.syncRegister({ displayName: "My Agent" });
// POST /agent/sync/register

{
  "data": {
    "agent": {
      "agentId": "agt_…",
      "displayName": "My Agent",
      "status": "synced",
      "fileCount": 42,
      "totalSize": 918240,
      "lastSync": "2026-07-01T12:00:00.000Z"
    }
  }
}

Read the manifest

The manifest lists every backed-up file with its content hash and size — compare it against local files to decide what changed.

const manifest = await client.syncGetManifest();
// GET /agent/sync/manifest
// { version, agentId, lastSync, files: { "<path>": { hash, size, modified } } }

Upload: presign, then confirm

Uploading is two steps. First ask for a presigned put URL for each file:

const { urls } = await client.syncPresign({
  files: [{ path: "notes/todo.md", operation: "put", contentType: "text/markdown" }],
});
// POST /agent/sync/presign

PUT the file bytes to the returned url, then confirm the upload so it’s recorded in the manifest:

await client.syncConfirmUpload({
  filePath: "notes/todo.md",
  hash: "<sha256-of-contents>",
  size: 1024,
});
// POST /agent/sync/confirm

Restore

Ask for a bundle of presigned get URLs to reconstruct the workspace. Choose how much to restore with mode:

const bundle = await client.syncReconstruct({ mode: "full" });
// POST /agent/sync/reconstruct
// mode: "full" | "active" | "memory"

Each entry in bundle.files has a path and a presigned url; GET each one to pull the bytes down.

List and inspect

const { files } = await client.syncListFiles({ prefix: "notes/" });
// GET /agent/sync/files?prefix=notes/

const stats = await client.syncGetStats();
// GET /agent/sync/stats  →  { fileCount, lastSyncAt, ... }

Sessions

Saved sessions are backed up too and can be listed and read back individually.

const { sessions } = await client.syncListSessions();
// GET /agent/sync/sessions

const { content } = await client.syncGetSession(sessions[0].sessionId);
// GET /agent/sync/sessions/{sessionId}

Delete a file

const { removed } = await client.syncDeleteFile("notes/todo.md");
// DELETE /agent/sync/files/{filePath}

Shared files vs synced files

The endpoints above cover the agent’s own workspace. Files shared with the agent at the org, team, or project level are a separate, read-oriented surface — see Shared knowledge.