Multi-agent deployments need workspace sync strategy — docs assume single agent

Environment

• NemoClaw: 0.1.0
• OpenShell: 0.0.7
• OS: Ubuntu 22.04.5 LTS
• Container runtime: k3s v1.29 (containerd)
• Deployment: Multiple agents — one main agent plus per-user agents for a Teams-integrated setup

Problem

When running multiple agents in NemoClaw (e.g., a shared main agent plus dedicated per-user agents), each agent gets its own workspace directory:

/sandbox/.openclaw/workspace-main/
/sandbox/.openclaw/workspace-support/
/sandbox/.openclaw/workspace-ops/

The current documentation and tooling assume a single-agent deployment:

1. Docs reference a single workspace path. The backup/restore documentation only references /sandbox/.openclaw/workspace/ (singular) or workspace-main. There is no mention of multi-workspace layouts.

2. backup-workspace.sh handles one workspace. The provided backup script only targets a single workspace directory. Running multiple agents means multiple workspaces need backup, each with different content and update frequencies.

3. No shared file strategy. In practice, certain files need to be consistent across agent workspaces:

   • AGENTS.md (agent definitions and coordination rules)
   • Shared skills (e.g., custom skills installed for all agents)
   • Templates and reference files
   • Common configuration (e.g., TOOLS.md with shared infrastructure details)

   Currently there's no mechanism to sync these — each workspace is fully isolated, and changes made in one are invisible to others.

4. No multi-workspace discovery. There's no command or API to list all active workspaces. You have to manually inspect the filesystem to know which workspace-* directories exist.

Current Workaround

We built a bidirectional sync layer that runs alongside NemoClaw:

#!/bin/bash
# sync-workspaces.sh — runs every 5 min
PERSISTENT="/mnt/persistent/nemoclaw-shared"
SANDBOX="/sandbox/.openclaw"

# Files that should be shared across all agent workspaces
SHARED_FILES="AGENTS.md TOOLS.md"
SHARED_DIRS="skills/"

# 1. Collect from all workspaces → persistent shared volume
for ws in "$SANDBOX"/workspace-*/; do
  agent=$(basename "$ws")
  for f in $SHARED_FILES; do
    [ -f "$ws/$f" ] && cp -u "$ws/$f" "$PERSISTENT/$f"
  done
  for d in $SHARED_DIRS; do
    [ -d "$ws/$d" ] && rsync -au "$ws/$d" "$PERSISTENT/$d"
  done
done

# 2. Distribute shared files back to all workspaces
for ws in "$SANDBOX"/workspace-*/; do
  for f in $SHARED_FILES; do
    [ -f "$PERSISTENT/$f" ] && cp -u "$PERSISTENT/$f" "$ws/$f"
  done
  for d in $SHARED_DIRS; do
    [ -d "$PERSISTENT/$d" ] && rsync -au "$PERSISTENT/$d" "$ws/$d"
  done
done

# 3. Per-agent backup (unique files like SOUL.md, MEMORY.md, memory/)
for ws in "$SANDBOX"/workspace-*/; do
  agent=$(basename "$ws")
  mkdir -p "$PERSISTENT/agent-backups/$agent"
  tar czf "$PERSISTENT/agent-backups/$agent/backup-$(date +%Y%m%d-%H%M%S).tar.gz" \
    -C "$ws" SOUL.md MEMORY.md USER.md IDENTITY.md memory/ 2>/dev/null
done

This works but is brittle — conflict resolution is "last write wins," and there's no atomic sync guarantee.

Expected Behavior / Suggestion

1. Document multi-agent workspace layout. Explain that each agent creates workspace-<name>/ and describe which files are per-agent vs. which might need sharing.

2. Provide a multi-workspace backup script. Extend the official backup tooling to discover and back up all workspace-* directories, not just workspace-main.

3. Consider a shared mount for common files. For files like AGENTS.md and shared skills, a read-only shared mount (or symlink strategy) would be cleaner than sync scripts. For example:

   /sandbox/.openclaw/shared/          ← mounted once, read by all agents
   /sandbox/.openclaw/workspace-main/  ← per-agent, read-write
   /sandbox/.openclaw/workspace-ops/   ← per-agent, read-write
   

4. Add a workspace listing command. Something like nemoclaw workspaces list that shows all active agent workspaces with their last-modified timestamps.

Multi-agent is a natural deployment pattern for enterprise Teams integrations (shared agent + per-user agents), so this should be a first-class supported layout rather than something each deployer has to figure out independently.