Cloud Workspaces
📖 Best for: Everyone — anyone running tasks with the desktop client (YingClaw) who needs to sync local directories with the cloud and centrally manage files and history
📖 Reading time: 8 minutes
📖 In one sentence: YingCore edge-cloud collaboration landing point. Open Cloud Workspaces from the top nav (route/cloud-workspaces) to see every workspace you can access. All files land in object storage (MinIO); the working directory you pick in Workbench is a workspace here.
Two near-identical concepts: a workspace (cloud directory, the subject of this page) is NOT the same as File Management (RAGFlow native knowledge-base documents, unrelated to this page). The "working directory" you pick in Workbench = the "workspace" described here.
Feature Overview
Read the diagram in three sentences: the client uploads directly to object storage (never through the app server) → the server only manages metadata (size/hash/version) → the browser can upload, download, and rescue files from the recycle bin.
1. Core Value
- Edge-cloud sync is invisible: the desktop client watches local directory changes, computes SHA-256, gets a presigned URL, and uploads directly to object storage. The app server never touches bytes, so bandwidth cost is minimized.
- Files are the work-directory landing point: artifacts produced by tasks sync automatically. Log in to the same workspace from another machine and keep editing — multi-device handoff.
- Accidental deletes and overwrites are recoverable: the recycle bin restores items one by one within the retention window; version history records every upload so every change is traceable.
- Workspace is the permission unit: each workspace assigns Owner / Editor / Viewer roles — permissions are sliced by workspace, not by file.
- Everyone can use it, zero gating: no admin gate; which workspaces you see is decided by the backend based on ownership and membership — log in and start.
2. Main Capabilities
Workspace management
| Capability | Description | Common actions |
|---|---|---|
| Create workspace | Fill in name, description, capacity quota (0 = unlimited), and auto-sync toggle. The creator automatically becomes the owner. | Click "Create" at the top-right of the list page |
| Delete workspace (soft delete) | Custom confirmation popup. The backend cascades: abort background task turns → delete sessions under that directory → soft-delete the workspace → unbind robots referencing the workspace. Owner permission required. | "Delete" in the card's top-right menu |
| Workspace list | Centered search box (local filter by name/description) + 4-column responsive card grid. Cards show role tag (Owner/Editor/Viewer), last activity time, file count, and sync state. | Use the centered search box to filter by keyword |
File capabilities
| Capability | Description | Common actions |
|---|---|---|
| File explorer | Directory navigation, upload, download, seven types of online preview (image/PDF/text/JSONL/JSON/video/audio). The list shows name, size, sync state (directory/synced/pending), and generation number. | Double-click a file to preview/download |
| Presigned direct upload | Browser computes SHA-256 → creates a session → uploads directly to object storage → server reviews size and hash. Bytes never pass through the app server. | Click "Upload" in the toolbar |
| Version history | The server records every upload version and supports viewing and restoring a specific version (web uploads usually have only one version; for rollback, ask the admin to fetch it from the backend). | "Versions" tab on the detail page |
| Recycle bin | Lists deleted objects, shows deletion time and retention hint, supports restoring items one by one (recoverable within the retention window; irreversible after expiry). | "Deleted" tab on the detail page |
Sync and system directories
| Capability | Description | Common actions |
|---|---|---|
| Sync center | Auto-sync toggle (sync policy bit), pending upload queue, recent activity, recent changes, error center. | "Sync Center" tab on the detail page |
| Daily work report | Submit a daily report by date. Idempotent (re-submitting for the same day does not create multiple entries). | "Work Report" tab on the detail page |
| System directory views | Virtual views such as Session records / Agent artifacts / Agent artifacts & memory / Conflict files / Deleted files. | Left-side directory tree on the detail page |
3. Typical Use Cases
- Centralize task artifacts: when batch processing finishes on the client, the artifacts sync automatically into Cloud Workspaces. Pick up the result on another machine — no USB drive needed.
- Multi-device handoff: run half a job on the office PC, take it home on another machine — same workspace, same files, keep editing.
- Rescue accidental deletes: deleted a file by mistake? Go to the Deleted Files panel and restore it one by one within the retention window.
- Trace every change: a file got overwritten and you want the previous version? Walk through Version History to view a specific version's content and restore it.
- Work traceability: write a daily report in Daily Work Report every day. Capture "what was done in this directory today" so reviews have evidence.
4. Usage Guide
1. Entry
| Item | Description |
|---|---|
| List page | /cloud-workspaces |
| Detail page | /cloud-workspaces/workspace/:workspaceId (click a card to enter) |
| Navigation | Top-level nav "Cloud Workspaces" with a cloud icon |
| Permission | No admin gate, all logged-in users can see it; which workspaces you can see is decided by the backend based on ownership and membership |
Detail page has four tabs: File Explorer / Sync Center / Daily Work Report / Deleted Files.
2. Create a workspace
Dialog fields: Name (required, max 200), Description (multiline, max 2000), Capacity quota (numeric, 0 = unlimited), Auto sync (toggle, default on) → "Create" → the creator automatically becomes the owner.
3. File operations
Upload flow (invisible to the user; useful when reconciling issues):
- The browser computes SHA-256.
- The browser requests a presigned direct-upload URL.
- The browser uploads directly to object storage (never through the app server).
- The server is notified of completion, reviews the size and hash, then marks the file as "synced".
Common prompts (so you know what they mean when you see them):
| Scenario | Message essentials |
|---|---|
| Direct upload blocked | Check object storage's CORS and reverse-proxy routing |
| Large file | Only the first 512 KB is shown (not an upload failure) |
| Type not supported | Download to view (does not break sync) |
| Cloud has no content | Distinguish between "file is empty" and "content is lost" |
| Sync paused | Prompt to resume; after resuming, show "sync resumed" |
4. Delete a workspace
Custom confirmation popup "Are you sure you want to delete this workspace? Its cloud objects will be marked as deleted" → the backend cascades in order: abort background task turns → delete sessions under that directory → soft-delete the workspace → unbind robots referencing the workspace. Owner permission required.
5. Exception handling and rollback
| Problem | Action |
|---|---|
| Browser blocks direct upload | Check object storage CORS and reverse-proxy routing, retry once |
| "Synced" but cannot open | First suspect that the upload did not complete (direct upload blocked or wrong presigned URL); re-upload once and it usually works |
| Accidental delete | Restore one by one from the Deleted Files tab (within the retention window) |
| Want to roll back an overwrite | Ask the admin to fetch version history from the backend (no entry on the web page) |
| Abnormal sync state | Check the Error Center in Sync Center; the pending upload queue can be retried |
5. Best Practices
- Cloud Workspaces ≠ the "File Management" page: "File Management" is RAGFlow's native knowledge-base document management — a different system from this page. Don't confuse them.
- The Workbench working directory = a Cloud Workspace: the "working directory" you pick in Workbench is a workspace here. To continue editing an artifact from a previous step, return to the same workspace.
- Don't rely on capacity quota for limiting: the backend does not currently enforce the quota — it is a display-only field. If you need capacity governance, find another way (or wait for a future release).
- Use one workspace per clear purpose: a workspace is both a sync unit and a permission unit. Mixing files from multiple teams/projects in one workspace makes permissions impossible to slice.
- Grant the minimum role needed: if Viewer is enough, don't grant Editor — Editors can upload, rename, and delete files, and deletes must be rescued from the recycle bin.
- Confirm three things before deleting a workspace: ① Is the client still syncing this directory? ② Does it contain files used by other projects? ③ Is the workspace bound as a working directory by any robot? Deleting a workspace cascades: abort turns, delete sessions, and unbind robots.
- The recycle bin is not permanent: deleted files are recoverable within the retention window. For truly important content, download a copy first before deleting.
- Don't expect to share cloud file links directly: Cloud Workspaces has no share-link feature. To give a file to someone else, download it and forward it, or add them to the workspace (contact the admin for member management; the current page does not provide this UI).