feat: support admin-managed protected file updates in sandboxes

[cloudant42]

Problem Statement

OpenShell can protect trusted sandbox config files such as /sandbox/.openclaw/openclaw.json by making them root-owned or read-only, but there does not appear to be a first-class admin/control-plane path to update those files after sandbox creation.

That creates an operational gap:

• the sandbox agent cannot modify the file, by design
• the admin also lacks a clear OpenShell-native way to update it
• protected config becomes locked rather than managed

This matters for trusted runtime config like openclaw.json, which may need post-provisioning changes such as enabling ACP or adding a protected secondary agent, while still remaining non-writable to the sandbox agent.

Proposed Design

Add a narrow control-plane-only apply path for explicitly declared admin-managed files.

Example:

openshell sandbox config apply \
  <sandbox> \
  --path /sandbox/.openclaw/openclaw.json \
  --from ./openclaw.json

Constraints

• only files explicitly marked admin-managed are eligible
• the apply runs with supervisor/control-plane authority, not as the sandbox user
• no arbitrary shell, exec, or generic privileged write primitive is exposed
• updates are full-file replacement, ideally atomic
• ownership/mode remain protected after apply
• changes are recorded as audited admin events
• structured files such as JSON could optionally be validated before commit

This would preserve isolation while making protected config operationally manageable.

Alternatives Considered

1. Leave the file writable to the sandbox agent
   Rejected because trusted config should not be agent-mutable.

2. Keep the file root-owned / read-only only
   Rejected because it protects integrity but blocks legitimate admin updates.

3. Require manual host/container intervention outside OpenShell
   Rejected because it bypasses the control plane and is harder to standardize and audit.

4. Recreate the sandbox for every protected config change
   Possible as a fallback, but too heavy for routine config changes.

Agent Investigation

With "create-spike" generated:

• • OpenShell currently has no admin file-apply primitive; UpdateConfig only supports policy replacement or a single setting mutation, not path + file payload updates. proto/openshell.proto:443 crates/openshell-server/src/
    grpc.rs:1107
• The settings channel is intentionally narrow and allowlisted. In the current code, production registered settings are effectively empty, and unknown keys are rejected. crates/openshell-core/src/settings.rs:33 crates/openshell-
  server/src/grpc.rs:2834
• Generic binary payloads are not available through normal settings updates; bytes are only used for the reserved global policy delivery path, so settings cannot be repurposed into protected file sync as-is. crates/openshell-
  server/src/grpc.rs:1142 crates/openshell-server/src/grpc.rs:2845
• Supervisor-managed filesystem setup exists only at startup for read_write paths. Static filesystem/process controls are applied before the child starts and are not designed for post-create protected file replacement. crates/
  openshell-sandbox/src/lib.rs:1361 architecture/sandbox.md:304
• The sandbox already polls the gateway for config revisions, so a future admin-managed file channel could reuse the existing change-detection flow, but today settings-only changes are just observed and logged, not materialized
  into files. crates/openshell-server/src/grpc.rs:888 crates/openshell-sandbox/src/lib.rs:1519
• The issue should stay generic: openclaw.json is a good motivating example, but the platform need is a control-plane-managed protected file mechanism for explicitly allowlisted paths, not an OpenClaw-specific exception. docs/
  sandboxes/community-sandboxes.md:43

Checklist

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