OpenShell sandboxes for OpenClaw

Sandboxing is the part of an agent platform that decides how much damage a bad instruction can do. OpenClaw already ships its own backends, and OpenShell is the option for teams who would rather hand that job to a managed service, on the same host or somewhere else entirely. The plugin keeps the OpenClaw Gateway in charge of the agent and the host side plugins, and hands only sandbox lifecycle and command execution to the other side. What you get in return is a clean separation and one configuration decision that matters more than all the others.

What the plugin does

• OpenClaw delegates sandbox creation, lookup, deletion and connection details to the OpenShell command line tool and then executes commands over SSH, reusing the same transport and remote filesystem bridge as the generic SSH backend.
• The OpenShell gateway that manages those sandboxes is a separate thing from the OpenClaw Gateway, it can run them locally with Docker, Podman or virtualisation or place them on separate infrastructure, and a local gateway requires no cloud account.
• The service account that runs the Gateway must see the same tool, gateway registration, credentials and workspace selection as your interactive shell, because a path or workspace variable exported in a terminal does not automatically reach a background service.
• Ordinary tool operations use a timeout of one hundred and twenty seconds by default, while sandbox creation is always given at least three hundred seconds so that image builds and first time provisioning are not cut short.

Keep API keys in OpenShell providers rather than adding them to sandbox environment variables.

Mirror or remote

Mirror mode is the default and keeps the local workspace canonical. Before a command runs the local workspace is synced into the sandbox, and after it finishes the remote workspace is synced back. A lock covers the complete upload, command and download, or a complete file read or mutation and its synchronisation, and separate backend handles share that lock. Working directory checks inspect the host directories that will be uploaded and release the lock before returning, so an abandoned check cannot block later tools. The tradeoff is an upload and a download on every execution turn, and the warning that goes with it is that external editors and other Gateway processes do not participate in the lock, so a download can replace edits made while a command was running. Remote mode inverts all of that, because the remote workspace is seeded once from local on first use, is never re-seeded once it holds content, and afterwards reads, writes, edits and patches happen directly on the remote side with nothing synced back. Initialisation is serialised per remote runtime, but after that commands and file tools can overlap, including across agent turns, so a background command can end up waiting for a file written by a later turn. The summary given in the reference is that mirror suits development workflows while remote suits long running agents and continuous integration, and that host edits made after the seed stay invisible until the sandbox is recreated.

Recreate is destructive

• Recreating a scope deletes the remote workspace and lets the next use seed a fresh one, which mainly resets the execution environment in mirror mode but destroys canonical remote only files in remote mode.
• Recreation is required after changing the backend, the sandbox source, the workspace mode, the policy file, the provider list, the GPU or automatic provider flags or either remote directory, and it has to be done while the old gateway and workspace are still selected.
• Remote directories must be absolute paths under the managed sandbox or agent roots and must not overlap, and since standard unprivileged images often cannot create the default agent directory, two non overlapping directories beneath the already writable sandbox root are the simpler answer.

In mirror mode the workspace is uploaded before each command execution and downloaded afterwards, so the cost is visible on every turn, while what a sandboxed session may run at all is a separate question answered by sandbox tool policy.

Why the boundary holds

The hardening notes are the most revealing part of the page. The mirror filesystem bridge pins the local workspace root and rechecks canonical paths before every read, write, directory creation, removal and rename, rejecting mid path symlinks, so a symlink swap or a remounted local workspace cannot redirect file access outside the mirrored tree. Synchronisation also excludes version control data and hook directories in both directions, so repository credentials, history and trusted hook code stay on the Gateway host instead of being copied into an untrusted sandbox. Entries that cannot be represented, such as symlinks, sockets and named pipes, are never copied into either workspace, and existing host entries of those types survive even if the sandbox deletes or replaces their directories. None of that is decoration, since it is what makes it reasonable to hand execution to a managed sandbox, and the same reasoning applies when that work runs on remote infrastructure. The limits are stated just as plainly, including no sandbox browser on this backend, one OpenShell workspace per plugin instance, and Docker specific settings that simply do not apply here.

On Diali

On Diali each customer runs their own assistant. Channels are connected from the dashboard, the runtime configuration is generated from it and replaced at each release, and state lives on a persistent volume, with daily snapshots and one-click restore available through the Backups add-on (included on Max). Hosted OpenClaw on Diali describes the hosted shape and Diali security covers the rest.

• Mirror keeps local canonical, remote keeps the sandbox canonical.
• Recreate in remote mode deletes files that exist nowhere else.
• A background service does not inherit your shell environment.