Workspace

Workspace is Flocks' project-level organizational boundary and file workspace. It holds the files, knowledge materials, runtime outputs, test data, and some project-level capabilities involved in a team, project, or customer delivery, so Rex, Agents, Workflows, Task Center, and users can all work around the same context.

For users, Workspace is not just a directory. It is where a project keeps its working files and outputs. Uploaded sample data, Agent-generated reports, Workflow test results, and historical outputs from scheduled tasks are usually accumulated here.

1. Purpose

1.1 What Workspace Solves

Workspace mainly solves four problems:

• File entry point: users can upload alerts, logs, PDFs, spreadsheets, configuration files, playbook files, and more for Rex to reference in sessions, Agents, or Workflows.
• Output archive: reports, intermediate data, JSON, Markdown, screenshots, and other outputs generated by Agents, Workflows, and Task Center are written to a shared location.
• Project isolation: different projects, customers, and demo environments can use different Workspaces to avoid mixing materials and outputs.
• Experience retention: knowledge materials and memory files help Rex continue understanding project background in later sessions.

Sessions handle interaction, Agents / Workflows handle execution, Task Center keeps recurring work running, and Workspace maintains inputs, outputs, and project context.

1.2 Relationship with Other Modules

Module	Relationship
Session Management	Session attachments are uploaded to Workspace, and reports generated by Rex are also usually written there.
Task Center	Input snapshots, intermediate data, and final reports from task execution are usually archived to Workspace by date or task.
Agent	Agents can read sample data, knowledge materials, and historical outputs in the current Workspace.
Workflow	Workflow test data, node outputs, and production run results usually land in Workspace.
Skills	Skills can guide Rex on how to use materials, templates, and historical results in Workspace.
Tools	Tools can read from or write to Workspace during execution, subject to tool permissions and sandbox configuration.

2. Use Cases

2.1 Good Fits for Workspace

• Upload sample data: give Rex alert JSON, syslog samples, vulnerability scan reports, or asset inventories for analysis.
• Keep runtime outputs: save inspection reports, triage results, data collection results, and Workflow test data.
• Run multiple projects in parallel: keep each project or customer's files and outputs separate for later review.
• PoC and delivery: keep demo data, generated Agents / Workflows, and runtime reports in one workspace for packaging and delivery.
• Archive scheduled tasks: store reports and structured results generated by scheduled tasks by date.
• Multi-account collaboration: in Pro environments, each user has a private Workspace directory, while team capabilities can still be shared.

2.2 When Workspace Usually Needs No Manual Attention

For personal use, one-off Q&A, and simple tasks without attachments or saved outputs, you usually do not need to manage Workspace manually. Flocks uses the default Workspace, and Rex writes to outputs/ when needed.

But whenever customer materials, batch data, scheduled tasks, or reports that need retention are involved, plan the Workspace deliberately.

3. Workspace Sources and Directory Conventions

3.1 Default Workspace

The default Workspace is located at:

~/.flocks/workspace

After Flocks starts, it automatically creates common subdirectories such as outputs/ and knowledge/. If there are no special requirements, use the default Workspace directly.

3.2 Specify Workspace with an Environment Variable

You can override the default location with FLOCKS_WORKSPACE_DIR:

export FLOCKS_WORKSPACE_DIR=/data/flocks-workspace

This is suitable when placing Workspace on an external disk, NAS, container mount, or dedicated data partition.

3.3 Typical Directory Structure

A typical Workspace looks like this:

<workspace-root>/
├── outputs/          # Outputs generated by Agents, Workflows, and Task Center
├── knowledge/        # User-curated knowledge materials, templates, and project data
├── shared/           # Shared area for Pro or team scenarios
│   ├── outputs/
│   └── knowledge/
└── users/            # User-private area in Pro multi-account scenarios
    └── <username>/
        └── outputs/

The actual directories vary by version, deployment mode, and whether Pro multi-account capabilities are enabled.

3.4 User-Level, Project-Level, and Shared Capabilities

Some Flocks plugin capabilities support user-level and project-level installation, but those capability directories are not managed by the Workspace file module. For example, Skills:

• User-level Skills are located at ~/.flocks/plugins/skills/.
• Project-level Skills are located in .flocks/plugins/skills/ in the current project and are version-controlled alongside project files.
• Workspace handles business files, uploads, runtime outputs, and memory files. It is not the storage directory for project-level Skills.

In Pro multi-account environments, each user has private conversation history and a private Workspace directory. Platform capabilities such as Agents, Skills, Tools, devices, tasks, Workflows, models, and channels are still shared by default, making team maintenance easier.

4. WebUI Flow

4.1 Open the Workspace Page

Go to AI Workspace -> Workspace from the sidebar. The page description is "file upload, Agent output, and memory browsing" and usually contains two tabs:

• File Management: browse, upload, edit, download, and delete Workspace files.
• Memory Files: read-only view of memory files automatically written by Rex and other Agents.

4.2 File Management

The File Management page supports common file operations:

• View the directory tree and file list.
• Go to the parent directory and refresh the current directory.
• Create directories.
• Drag-and-drop upload or click to upload files.
• Read text file content.
• Edit and save text files.
• Download a single file.
• Delete files or directories.
• Move files.
• Select multiple files and download them as a zip.

Binary files can be downloaded but usually cannot be previewed directly. Text files can be read and edited on the page.

4.3 Upload Files for Rex to Use

After uploading an attachment in a session, or uploading a file on the Workspace page, you can tell Rex directly:

Read alerts/sample-ndr-alert.json in Workspace and help me analyze these alerts.

You can also provide sample data when creating a Workflow:

Use samples/syslog-example.txt in Workspace as the sample and help me create a syslog parsing Workflow.

Uploading sample data is especially important for Workflows. After generating a workflow, Rex can immediately use the sample data for single-node tests and full integration tests.

4.4 View Runtime Outputs

After Agents, Workflows, and Task Center run, common outputs include:

• Raw input snapshots.
• Intermediate JSON data.
• Markdown triage reports.
• Inspection checklists.
• Workflow node test results.
• Reports from each scheduled task run.
• Summaries or full content before outbound channel delivery.

These contents are usually written to outputs/ and archived by date, task name, Workflow name, or execution ID.

4.5 View Memory Files

Memory files are automatically written by Rex and other Agents to record project background, important facts, historical handling experience, and long-term context. The Workspace page provides a read-only view so users can see what the system has remembered.

If memory content is inaccurate, explicitly tell Rex to correct the memory in a session instead of treating memory files as normal outputs and modifying them casually.

5. Directory and File Governance

5.1 Meaning of outputs

outputs/ is not a log directory; it serves as a repository for business artifacts and reusable execution outputs. It is suitable for:

• Alert triage results.
• Asset inspection reports.
• Workflow test data.
• Batch query results.
• Scheduled outputs from Task Center.
• Reports deliverable to users or customers.

Logs are for troubleshooting; outputs are for reuse, auditing, and delivery. When locating task execution issues, checking outputs/ first often shows more quickly how far the process ran.

5.2 Meaning of knowledge

knowledge/ is suitable for user-curated project knowledge, such as:

• Customer network background.
• Asset grouping descriptions.
• Alert triage standards.
• Notification templates.
• Report templates.
• Handling procedure documents.

Rex and Agents can read these materials as project context when executing tasks.

5.3 File Naming Recommendations

For long-term use, adopt stable naming:

outputs/
├── 2026-06-10/
│   ├── ndr-alert-triage.json
│   └── ndr-alert-triage.md
└── device-inspection/
    ├── 2026-06-10.md
    └── 2026-06-11.md

Include date, task name, data type, or execution target. This makes it easier for Rex to summarize, compare, or trace outputs later.

5.4 Docker Deployment and Mounts

In Docker deployments, the Workspace directory must be mounted to a host directory. Otherwise, outputs generated inside the container are inconvenient to view and back up on the host.

If a session says "report saved" but you cannot find it on the host, first check:

1. Whether Workspace is mounted correctly.
2. What FLOCKS_WORKSPACE_DIR Flocks actually used at runtime.
3. Whether the file was saved to the current user's private Workspace.
4. Whether it was saved under an outputs/<date>/ subdirectory.

5.5 Permissions and Sandbox

Some tools or Agents run in a sandbox. Sandbox access to Workspace may be read-only, read-write, or unavailable, depending on the tool and system configuration.

If a task needs to generate files but nothing is written to disk, check:

• Whether the tool has permission to write Workspace.
• Whether the runtime environment can access the directory.
• Whether the Docker mount allows writes.
• Whether the current user has directory permissions.

6. Pro Multi-Account Scenarios

6.1 User-Private Workspace

In Pro multi-account environments, each user has private conversation history and a private Workspace directory. Regular users can only see and manage their own files and session outputs.

This isolates personal analysis, uploaded files, and draft reports so different users do not see each other's private work.

6.2 Team-Shared Capabilities

Pro multi-account isolation applies to user-private data, not all platform capabilities. Agents, Skills, Tools, devices, tasks, Workflows, models, and channels are usually still shared team capabilities.

Common collaboration flow:

• Users upload sample data and verification results in their own Workspace.
• After validation matures, publish the Agent / Skill / Workflow as a team-shared capability.
• Task Center uses the shared capability for scheduled execution, and outputs are written to the configured Workspace or shared area.

6.3 Historical Workspace Migration

After upgrading from single-account to multi-account, use the admin CLI to migrate the historical single-user Workspace to the multi-account layout:

flocks admin migrate-workspace-to-user --admin-user-id <user_id> --dry-run
flocks admin migrate-workspace-to-user --admin-user-id <user_id>

Run --dry-run first to preview the migration result, then run the actual migration.

7. Run, Verify, and Adjust

7.1 Confirm the Current Workspace Before Running Tasks

Before running important tasks, confirm the current Workspace, especially in multi-project, multi-customer, or Docker deployment environments. You can ask Rex in a session:

What is the current Workspace path? Where will this task's outputs be saved?

7.2 Output Acceptance

After a task, Agent, or Workflow finishes, check:

• Whether expected files were generated under outputs/.
• Whether file names reflect date, task, and content.
• Whether JSON results are structured and readable by later Workflows.
• Whether Markdown reports are suitable for direct sending or archiving.
• Whether channel messages contain only summaries and full reports are saved in Workspace.

7.3 Troubleshooting When Files Are Missing

Use this order:

1. Refresh the current directory on the Workspace page.
2. Check outputs/ and today's date directory.
3. Ask Rex "Where was the file generated just now saved?"
4. Confirm the current runtime user and current Workspace.
5. In Docker scenarios, check the mounted directory.
6. View workspaceDirectory or output descriptions in Task Center execution details.

7.4 Archive and Migration

Workspace is essentially a directory. It can be copied, packaged, or synced to another machine. This is suitable for:

• Delivering the whole PoC after completion.
• Archiving after a project ends.
• Migrating from test to production.
• Syncing sample data and reports across machines.

Before migration, remove temporary files and unrelated outputs. Keep outputs/, knowledge/, necessary project-level plugin directories, and documentation.

8. Real Example: Alert Triage Project Workspace

8.1 Prepare Sample Data

The user first uploads to Workspace:

knowledge/customer-background.md
knowledge/alert-triage-standard.md
samples/ndr-alerts.json

Then tells Rex in a session:

Based on the customer background, triage standard, and NDR sample alerts in Workspace, help me create an alert triage Workflow.

8.2 Generate and Test the Workflow

Rex reads the sample data, generates the Workflow, and writes single-node test and full-flow test results to:

outputs/2026-06-10/ndr-alert-triage-test/

After checking the test report, the user asks Rex to adjust node logic or output format.

8.3 Convert to a Long-Running Task

After Workflow acceptance, configure it in Task Center to run every hour. Each run's outputs are archived by date:

outputs/2026-06-10/ndr-alert-triage-hourly/
outputs/2026-06-11/ndr-alert-triage-hourly/

Later, to generate a weekly report, Rex can directly summarize these Workspace outputs without pulling and triaging all historical data again.

9. FAQ

9.1 The Session Says "Report Saved," but I Cannot Find It. What Should I Do?

First refresh outputs/ on the Workspace page, then check today's date directory. In a Pro multi-account environment, confirm whether it was saved to the current user's private Workspace. In Docker deployments, confirm that the host mount directory is correct.

9.2 Can the Workspace Page Edit All Files?

Text files can usually be read and edited. Binary files can usually only be downloaded. Memory files are read-only views and should not be modified directly as normal files.

9.3 Can an Existing Workspace Be Packaged and Migrated?

Yes. Workspace is essentially a directory and can be migrated with tar, rsync, or other backup tools. After migration, start Flocks and confirm on the Workspace page that files, outputs, and memory views are normal.

9.4 Can Project-Level Agents / Skills / Workflows Be Reused by Other Projects?

By default, project-level capabilities are visible only in the current project. To reuse them across projects, install stable capabilities into the user-level directory, or organize them as a team-shared plugin and install it in other projects.

9.5 Will Deleting Flocks Lose Workspace Data?

As long as the Workspace directory itself is not deleted, Workspace outputs are not lost automatically when the program is stopped or uninstalled. Before cleanup or uninstall, confirm whether FLOCKS_WORKSPACE_DIR and ~/.flocks/workspace contain data that should be kept.

9.6 What Is the Relationship Between Task Center and Workspace?

Task Center is responsible for task scheduling and execution records. Workspace stores file outputs produced during task execution. When troubleshooting tasks, use Task Center to inspect status and errors, and Workspace to inspect the files actually generated.

10. Related Modules

• Session Management: Session attachments and Rex outputs usually enter Workspace.
• Task Center: Scheduled task outputs land in Workspace outputs/.
• Agent: Agents can read Workspace materials and generate reports.
• Workflow: Workspace carries Workflow test data and runtime results.
• Skills: Skills can guide Rex on using Workspace materials.
• Tools: Tool access to Workspace is affected by permissions and sandbox configuration.
• Account Management: User-private Workspace and migration commands in Pro multi-account deployments.