openclaw - 💡(How to fix) Fix [Feature]: Pre-container-creation hook for dynamic sandbox bind mounts [1 participants]

Summary

Allow a host-side hook (script or callback) to run before a sandbox container is created, enabling dynamic resolution of sandbox.docker.binds based on session context (channel, user, metadata).

Problem to solve

In multi-user gateway deployments with differentiated file access (governance levels, compliance tiers, client data isolation), each user session needs a different subset of host directories mounted into its sandbox container.

Today, agents.defaults.sandbox.docker.binds is static per agent config — every session of the same agent gets identical filesystem access. There is no way to vary bind mounts per session based on user identity or channel context.

Concrete scenario: A team gateway routes users via channels. Depending on the user's governance level (derived from channel metadata), the sandbox should only mount the directories that user is authorized to access. User A sees /data/public, user B sees /data/public + /data/confidential.

Current workarounds and why they fall short:

Proposed solution

Add an optional sandbox.docker.resolveBinds config field pointing to a host-side executable. The gateway invokes it before container creation, passing session context on stdin. The script returns bind mount entries on stdout.

agents:
  defaults:
    sandbox:
      docker:
        resolveBinds: "./scripts/resolve-binds.sh"
        binds: ["/data/shared:/workspace/shared:ro"]  # static, always included

Script contract:

stdin:  {"channelId": "C123", "userId": "U456", "agentName": "support-agent"}
stdout: ["/data/confidential:/workspace/confidential:ro"]
exit 0 → merge with static binds
exit !0 → fail container creation with error

Security constraints (same validation as static binds):

• Output validated against existing blocklist (/etc, /proc, /sys, docker.sock, credential dirs)
• Timeout enforced (e.g. 5 seconds) to prevent gateway hangs
• Invalid JSON or blocked paths → container creation fails, clear error surfaced to user

Alternatives considered

• One agent per access level: Works but scales poorly (N governance levels × M agent configs). Maintenance burden grows linearly.
• Mount everything + restrict via setupCommand: Mount points remain visible to the agent even if ACLs block reads. Violates principle of least privilege. A sufficiently capable model might attempt to circumvent in-container restrictions.
• External wrapper that rewrites config before gateway start: Race conditions with concurrent sessions. Config reloads during active sessions could affect other users.
• Plugin before_agent_start hook: Runs after container creation, cannot influence bind mounts. Also currently cannot cancel session start (#19420, closed as not planned).

Impact

• Affected: Any multi-user OpenClaw deployment with differentiated file access (compliance-driven teams, consulting firms with client data isolation, multi-tenant SaaS platforms)
• Severity: Blocks workflow — currently no secure way to run governance-level file isolation per session
• Frequency: Every session start in affected deployments
• Consequence: Either all users get access to all files (security risk) or operators maintain N duplicate agent configs (operational burden)

Evidence/examples

• Comparable patterns: Kubernetes admission webhooks (mutate pod specs including volume mounts before scheduling), VS Code Dev Containers initializeCommand (runs on host before container creation), Docker Compose profiles (conditional service configuration based on environment)
• Related issues: #30334 (plugin config injection — similar need for dynamic per-session container config), #22669 (bind mount ordering — shows binds are already a friction point), #19420 (before_agent_start cannot cancel sessions — closed as not planned)

Additional information

• The hook must run on the host (not inside the container) since it determines container creation parameters.
• Should be composable with static binds (merge by default, with an option to replace).
• A TypeScript function alternative (instead of external script) could integrate more tightly with gateway internals but reduces deployment flexibility.