OpenShell: Managed Sandbox Backend for OpenClaw Agents

OpenShell provides a managed sandbox environment. Rather than handling Docker containers on the local machine, OpenClaw hands off sandbox management to the openshell command line tool, which provisions remote environments and runs commands over SSH.

This plugin uses the same SSH transport and remote file system bridge found in the standard SSH backend, and incorporates OpenShell lifecycle management (sandbox create/get/delete/ssh-config) along with an optional mirror workspace synchronization mode.

Prerequisites

• The OpenShell plugin must be installed (openclaw plugins install @openclaw/openshell-sandbox)
• openshell CLI must be present on PATH (or configured with a custom location via plugins.entries.openshell.config.command)
• An OpenShell account with sandbox access is required
• OpenClaw Gateway must be running on the host

Quick start

openclaw plugins install @openclaw/openshell-sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

After restarting the Gateway, OpenClaw will create an OpenShell sandbox on the next agent turn and direct tool execution through it. Confirm this is working with:

openclaw sandbox list
openclaw sandbox explain

Workspace modes

This choice is the most critical one when using OpenShell.

mirror (default)

With plugins.entries.openshell.config.mode: "mirror", the local workspace remains the authoritative source:

• Before exec runs, OpenClaw copies the local workspace into the sandbox.
• After exec completes, OpenClaw copies the remote workspace back to the local machine.
• File tools operate through the sandbox bridge, but the local copy stays authoritative between turns.

Ideal for development scenarios: changes made locally outside OpenClaw are picked up on the next execution, and the sandbox behaves similarly to the Docker backend.

Downside: every execution turn requires both an upload and a download.

remote

With mode: "remote", the OpenShell workspace becomes the authoritative source:

• When the sandbox is first created, OpenClaw populates the remote workspace from the local machine once.
• After that point, exec, read, write, edit, and apply_patch work directly on the remote workspace. OpenClaw does not copy remote changes back to the local machine.
• Media reads at prompt time still function (file and media tools read through the sandbox bridge).

Best suited for long running agents and CI pipelines: lower overhead per turn, and local edits cannot accidentally overwrite remote state.

Warning

Any file edits made on the host outside OpenClaw after the initial seed will not be visible to the remote sandbox. Use openclaw sandbox recreate to re seed.

Choosing a mode

Configuration reference

All OpenShell configuration is located under plugins.entries.openshell.config:

Both remoteWorkspaceDir and remoteAgentWorkspaceDir must be absolute paths and must fall within the managed roots /sandbox or /agent; any other absolute path is rejected.

Settings that apply at the sandbox level (mode, scope, workspaceAccess) are placed under agents.defaults.sandbox just like any other backend. For the complete matrix, refer to Sandboxing.

Examples

Minimal remote setup

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}

Mirror mode with GPU

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "agent",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "mirror",
          gpu: true,
          providers: ["openai"],
          timeoutSeconds: 180,
        },
      },
    },
  },
}

Per-agent OpenShell with custom gateway

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    list: [
      {
        id: "researcher",
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    ],
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          policy: "strict",
        },
      },
    },
  },
}

Lifecycle management

# List all sandbox runtimes (Docker + OpenShell)
openclaw sandbox list

# Inspect effective policy
openclaw sandbox explain

# Recreate (deletes remote workspace, re-seeds on next use)
openclaw sandbox recreate --all

In remote mode, the recreate operation holds special significance: it removes the canonical remote workspace for the given scope, and the subsequent use generates a fresh one from local files. For mirror mode, recreate primarily resets the remote execution environment, as local remains canonical.

Run recreate after modifying any of the following:

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy

Security hardening

The mirror-mode filesystem bridge locks the local workspace root and verifies canonical paths (using realpath) prior to each read, write, mkdir, remove, and rename operation, blocking symlinks within the path. A symlink substitution or remounted workspace cannot redirect file access beyond the mirrored tree.

Current limitations

• The OpenShell backend does not support the sandbox browser.
• sandbox.docker.binds has no effect on OpenShell; creating a sandbox fails when binds are configured.
• Docker-specific runtime settings under sandbox.docker.* (excluding env) work exclusively with the Docker backend.

How it works

1. OpenClaw calls sandbox get for the sandbox name (including any configured --gateway/--gateway-endpoint); on failure, it generates one using sandbox create, passing --name, --from, --policy when defined, --gpu when active, --auto-providers/--no-auto-providers, and one --provider flag per configured provider.
2. OpenClaw invokes sandbox ssh-config for the sandbox name to retrieve SSH connection information.
3. Core writes the SSH configuration to a temporary file and establishes an SSH session through the same remote filesystem bridge used by the generic SSH backend.
4. In mirror mode: synchronize local to remote before execution, run, then sync back after.
5. In remote mode: seed once during creation, then work directly on the remote workspace.

Related

• Sandboxing - modes, scopes, and backend comparison
• Sandbox vs Tool Policy vs Elevated - debugging blocked tools
• Multi-Agent Sandbox and Tools - per-agent overrides
• Sandbox CLI - openclaw sandbox commands