feat(sandbox): openshell sandbox sync — continuous host-sandbox file sync with state backup

[mjamiv]

Problem Statement

Production agents running in OpenShell sandboxes accumulate critical state over time: workspace files (personality, memory, identity documents), config, auth profiles, and session history. Today there is no built-in mechanism to:

1. Continuously mirror sandbox state to the host — if the sandbox is destroyed (Docker restart, volume corruption, machine migration), agent persona and memory are lost
2. Push content into a running sandbox without SSH or manual openshell sandbox upload invocations
3. Maintain point-in-time snapshots for rollback if state gets corrupted

The existing sandbox upload / sandbox download commands are building blocks, but users must build their own cron + scripting layer on top. The gateway resume work in #487/#488 handles surviving restarts, but doesn't cover: (a) continuous backup during normal operation, (b) content delivery into sandboxes, or (c) recovery when a full rebuild is needed.

Real-world impact: We run 3+ always-on OpenClaw agents on Mac Minis (details in #487 comment). Every Docker restart destroys all agent state — personality, memory, conversation history, config. We built a host-side sync script as a workaround, but this belongs in the platform.

Proposed Design

New CLI command: openshell sandbox sync

openshell sandbox sync <NAME> [OPTIONS]

OPTIONS:
  --push-dir <PATH>       Local directory to push into sandbox (default: ~/sandbox-sync/<name>/push)
  --push-dest <PATH>      Sandbox destination for pushed files (default: /sandbox/sync)
  --backup-dir <PATH>     Local directory for pulled backups (default: ~/sandbox-sync/<name>/backup)
  --backup-paths <PATHS>  Comma-separated sandbox paths to back up (see defaults below)
  --interval <DURATION>   Sync interval for watch mode (default: 1h)
  --watch                 Run continuously at --interval instead of one-shot
  --snapshot              Also create a timestamped snapshot after pull
  --quiet                 Suppress non-error output

Default backup paths (agent-framework-aware)

The sync command should ship with sensible defaults for common agent frameworks:

# OpenClaw defaults (detected via /sandbox/.openclaw/)
- /sandbox/.openclaw/workspace/    # SOUL.md, IDENTITY.md, HEARTBEAT.md, USER.md, etc.
- /sandbox/.openclaw/openclaw.json # Gateway config
- /sandbox/.openclaw/agents/       # Auth profiles, session state

# Generic defaults (always included)
- /sandbox/.bashrc
- /sandbox/.claude/                # Claude Code memory/settings if present

Users can override with --backup-paths or a .openshell-sync.yaml config file in the sync directory.

Behavior

One-shot mode (openshell sandbox sync agent):

1. If push/ has contents → sandbox upload them to --push-dest
2. For each path in --backup-paths → sandbox download to backup/
3. If --snapshot → copy backup to backup/snapshots/YYYY-MM-DD-HHMMSS/

Watch mode (openshell sandbox sync agent --watch):

1. Runs one-shot sync immediately
2. Repeats at --interval
3. Creates one snapshot per calendar day automatically
4. Logs to ~/sandbox-sync/<name>/sync.log
5. Graceful shutdown on SIGINT/SIGTERM

Directory layout (created automatically)

~/sandbox-sync/<sandbox-name>/
├── push/                              ← Drop files here → uploaded to sandbox
├── backup/
│   ├── workspace/                     ← Latest agent state files
│   ├── config/                        ← Latest config
│   └── snapshots/2026-03-27-140000/   ← Point-in-time snapshots
├── sync.log                           ← Timestamped log
└── .openshell-sync.yaml               ← Optional per-sandbox config overrides

Integration with existing commands

• Uses sandbox upload and sandbox download internally — no new transport mechanism needed
• Respects .gitignore filtering on push (existing --no-git-ignore flag)
• Checks sandbox phase before syncing (skips if not Ready)
• Could later integrate with sandbox create --restore-from for full lifecycle

Config file format (optional)

# .openshell-sync.yaml
backup_paths:
  - /sandbox/.openclaw/workspace/
  - /sandbox/.openclaw/openclaw.json
  - /sandbox/.openclaw/agents/main/agent/auth-profiles.json
  - /sandbox/custom-data/
push_dest: /sandbox/sync
interval: 30m
snapshot: true
snapshot_keep: 7  # days

Alternatives Considered

1. Host-side shell script + cron (current workaround): Works but fragile — no sandbox health checks, no framework detection, no config file, each team reinvents it. Our implementation can serve as a reference.

2. Docker volume mounts: Would bypass the sandbox isolation model. Not compatible with OpenShell's security architecture.

3. Extend sandbox upload/download with --watch: Simpler but doesn't handle the bidirectional sync + backup + snapshot lifecycle. A dedicated sync command better communicates the intent.

4. Build into gateway resume (feat: gateway resume from existing state and persistent SSH handshake secret #487/feat(bootstrap): resume gateway from existing state and persist SSH handshake secret #488): Gateway resume handles restart survival but not continuous backup, content delivery, or cross-machine migration. These are complementary — sync runs during normal operation, resume handles the restart edge case.

Agent Investigation

Explored the existing CLI structure:

• sandbox upload and sandbox download use tar-over-SSH transport (crates/openshell-sandbox/src/ssh/)
• Sandbox phase checking exists in sandbox get — sync should reuse this
• The --sync flag on sandbox create already establishes the pattern of host↔sandbox file sync at the CLI level
• No existing watch/interval mechanism in the CLI — would need a simple loop or tokio interval in the Rust implementation
• The upload bug (destination treated as directory when file exists) documented in OpenClaw-init known issues affects sync reliability — should be fixed as a prerequisite or worked around

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[johntmyers]

This is something we will look to improve at the infrastructure level, not the user interface level. We've recently merged #739 and our future work on leveraging MicroVMs should continue to improve this. I will be closing this in favor of infrastructure based approaches.