Skip to main content

​
OpenShell

OpenShell is a managed sandbox backend for OpenClaw. Instead of running Docker containers locally, OpenClaw delegates sandbox lifecycle to the openshell 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 (sandbox create/get/delete, sandbox ssh-config) and an optional mirror workspace mode.

​
Prerequisites

  • The openshell CLI installed and on PATH (or set a custom path via 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:
{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "openshell",
        scope: "session",
        workspaceAccess: "rw",
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "openclaw",
          mode: "remote",
        },
      },
    },
  },
}
  1. Restart the Gateway. On the next agent turn, OpenClaw creates an OpenShell sandbox and routes tool execution through it.
  2. Verify: 
openclaw sandbox list
openclaw sandbox explain

​
Workspace modes

This is the most important decision when using OpenShell.

​
mirror

Use plugins.entries.openshell.config.mode: "mirror" when you want the local workspace to stay canonical. Behavior:
  • Before exec, OpenClaw syncs the local workspace into the OpenShell sandbox.
  • After 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.

​
remote

Use plugins.entries.openshell.config.mode: "remote" 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, exec, read, write, edit, and 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.
Important: if you edit files on the host outside OpenClaw after the initial seed, the remote sandbox does not see those changes. Use openclaw sandbox recreate to re-seed.

​
Choosing a mode

mirrorremote
Canonical workspaceLocal hostRemote OpenShell
Sync directionBidirectional (each exec)One-time seed
Per-turn overheadHigher (upload + download)Lower (direct remote ops)
Local edits visible?Yes, on next execNo, until recreate
Best forDevelopment workflowsLong-running agents, CI

​
Configuration reference

All OpenShell config lives under plugins.entries.openshell.config:
KeyTypeDefaultDescription
mode"mirror" or "remote""mirror"Workspace sync mode
commandstring"openshell"Path or name of the openshell CLI
fromstring"openclaw"Sandbox source for first-time create
gatewaystring—OpenShell gateway name (--gateway)
gatewayEndpointstring—OpenShell gateway endpoint URL (--gateway-endpoint)
policystring—OpenShell policy ID for sandbox creation
providersstring[][]Provider names to attach when sandbox is created
gpubooleanfalseRequest GPU resources
autoProvidersbooleantruePass --auto-providers during sandbox create
remoteWorkspaceDirstring"/sandbox"Primary writable workspace inside the sandbox
remoteAgentWorkspaceDirstring"/agent"Agent workspace mount path (for read-only access)
timeoutSecondsnumber120Timeout for openshell CLI operations
Sandbox-level settings (mode, scope, workspaceAccess) are configured under agents.defaults.sandbox as with any backend. See Sandboxing for the full matrix.

​
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

OpenShell sandboxes are managed through the normal sandbox CLI: 
# 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 remote 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 mirror mode, recreate mainly resets the remote execution environment because the local workspace remains canonical.

​
When to recreate

Recreate after changing any of these:
  • agents.defaults.sandbox.backend
  • plugins.entries.openshell.config.from
  • plugins.entries.openshell.config.mode
  • plugins.entries.openshell.config.policy
openclaw sandbox recreate --all

​
Current limitations

  • Sandbox browser is not supported on the OpenShell backend.
  • sandbox.docker.binds does not apply to OpenShell.
  • Docker-specific runtime knobs under sandbox.docker.* apply only to the Docker backend.

​
How it works

  1. OpenClaw calls openshell sandbox create (with --from, --gateway, --policy, --providers, --gpu flags as configured).
  2. OpenClaw calls 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 mirror mode: sync local to remote before exec, run, sync back after exec.
  5. In remote mode: seed once on create, then operate directly on the remote workspace.

​
See also