OpenShell

OpenShell is a managed sandbox backend for OpenClaw. Instead of running Docker containers locally, OpenClaw delegates sandbox lifecycle to the

CLI, which provisions remote environments with SSH-based command execution.

The OpenShell plugin reuses the same core SSH transport and remote filesystem bridge as the generic SSH backend. It adds OpenShell-specific lifecycle (

, ) and an optional workspace mode.

Prerequisites

• The
  text

  Copy

  openshell
  CLI installed and on
  text

  Copy

  PATH
  (or set a custom path via
  text

  Copy

  plugins.entries.openshell.config.command
  )
• An OpenShell account with sandbox access
• OpenClaw Gateway running on the host

Quick start

1. Enable the plugin and set the sandbox backend:

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

2. Restart the Gateway. On the next agent turn, OpenClaw creates an OpenShell sandbox and routes tool execution through it.

3. Verify:

bash
Copy
openclaw sandbox list
openclaw sandbox explain

Workspace modes

This is the most important decision when using OpenShell.

text

Copy

mirror

Use

when you want the local workspace to stay canonical.

Behavior:

• Before
  text

  Copy

  exec
  , OpenClaw syncs the local workspace into the OpenShell sandbox.
• After
  text

  Copy

  exec
  , OpenClaw syncs the remote workspace back to the local workspace.
• File tools still operate through the sandbox bridge, but the local workspace remains the source of truth between turns.

Best for:

• You edit files locally outside OpenClaw and want those changes visible in the sandbox automatically.
• You want the OpenShell sandbox to behave as much like the Docker backend as possible.
• You want the host workspace to reflect sandbox writes after each exec turn.

Tradeoff: extra sync cost before and after each exec.

text

Copy

remote

Use

when you want the OpenShell workspace to become canonical.

Behavior:

• When the sandbox is first created, OpenClaw seeds the remote workspace from the local workspace once.
• After that,
  text

  Copy

  exec
  ,
  text

  Copy

  read
  ,
  text

  Copy

  write
  ,
  text

  Copy

  edit
  , and
  text

  Copy

  apply_patch
  operate directly against the remote OpenShell workspace.
• OpenClaw does not sync remote changes back into the local workspace.
• Prompt-time media reads still work because file and media tools read through the sandbox bridge.

Best for:

• The sandbox should live primarily on the remote side.
• You want lower per-turn sync overhead.
• You do not want host-local edits to silently overwrite remote sandbox state.

Choosing a mode

Configuration reference

All OpenShell config lives under

:

Sandbox-level settings (

, , ) are configured under as with any backend. See Sandboxing for the full matrix.

Examples

Minimal remote setup

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

Mirror mode with GPU

json5
Copy
{
  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

json5
Copy
{
  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

OpenShell sandboxes are managed through the normal sandbox CLI:

bash
Copy
# 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

For

mode, recreate is especially important: it deletes the canonical remote workspace for that scope. The next use seeds a fresh remote workspace from the local workspace.

For

mode, recreate mainly resets the remote execution environment because the local workspace remains canonical.

When to recreate

Recreate after changing any of these:

• text

  Copy

  agents.defaults.sandbox.backend
• text

  Copy

  plugins.entries.openshell.config.from
• text

  Copy

  plugins.entries.openshell.config.mode
• text

  Copy

  plugins.entries.openshell.config.policy

bash
Copy
openclaw sandbox recreate --all

Security hardening

OpenShell pins the workspace root fd and rechecks sandbox identity before each read, so symlink swaps or a remounted workspace cannot redirect reads out of the intended remote workspace.

Current limitations

• Sandbox browser is not supported on the OpenShell backend.
• text

  Copy

  sandbox.docker.binds
  does not apply to OpenShell.
• Docker-specific runtime knobs under
  text

  Copy

  sandbox.docker.*
  apply only to the Docker backend.

How it works

1. OpenClaw calls
   text

   Copy

   openshell sandbox create
   (with
   text

   Copy

   --from
   ,
   text

   Copy

   --gateway
   ,
   text

   Copy

   --policy
   ,
   text

   Copy

   --providers
   ,
   text

   Copy

   --gpu
   flags as configured).
2. OpenClaw calls
   text

   Copy

   openshell sandbox ssh-config <name>
   to get SSH connection details for the sandbox.
3. Core writes the SSH config to a temp file and opens an SSH session using the same remote filesystem bridge as the generic SSH backend.
4. In
   text

   Copy

   mirror
   mode: sync local to remote before exec, run, sync back after exec.
5. In
   text

   Copy

   remote
   mode: seed once on create, then operate 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 --
  text

  Copy

  openclaw sandbox
  commands