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",
        },
      },
    },
  },
}

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

3. 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.

Choosing a mode

Configuration reference

All OpenShell config lives under plugins.entries.openshell.config:

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

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.
• 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.

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