OpenShell is a managed sandbox backend: Apus delegates sandbox lifecycle to the openshell CLI and executes commands over SSH. The selected OpenShell gateway can manage sandboxes locally with Docker, Podman, or virtualization, or run them on separate infrastructure. This OpenShell gateway is distinct from the Apus Gateway, which continues to run the agent and host-side plugins.

The plugin reuses the same SSH transport and remote filesystem bridge as the generic SSH backend, and adds OpenShell lifecycle (sandbox create/get/delete/ssh-config) plus an optional mirror workspace sync mode.

Prerequisites

• openshell CLI installed and on the Apus Gateway process's PATH (or a custom absolute path via plugins.entries.openshell.config.command)
• OpenSSH client available on the Gateway host
• OpenShell v0.0.88 or newer when configuring an OpenShell workspace
• An active, reachable OpenShell gateway with permission to create sandboxes. Local gateways do not require a cloud account
• A supported compute runtime on the OpenShell gateway host when using local sandboxes
• Apus Gateway running on the host

Install the CLI and configure an OpenShell gateway using the NVIDIA OpenShell documentation. Before configuring Apus, verify the OpenShell CLI as the same operating system user that runs the Apus Gateway:

openshell --version
openshell gateway list
openshell sandbox list

gateway list marks the active gateway with *. If no gateway is selected, run openshell gateway select <gateway-name>. To register an existing local gateway endpoint, run openshell gateway add http://127.0.0.1:8080 --local. Replace the endpoint with the address of your running gateway. For an authenticated remote gateway, follow its login flow with openshell gateway login <gateway-name>.

The Apus Gateway service must see the same OpenShell CLI, gateway registration, credentials, and OpenShell workspace selection as these preflight commands. A shell-only PATH or OPENSHELL_WORKSPACE setting does not automatically reach a background service.

Quick start

apus plugins install @openclaw/openshell-sandbox

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

Validate the configuration and restart the Apus Gateway:

apus config validate
apus gateway restart

On the next agent turn Apus creates an OpenShell sandbox and routes tool execution through it. Verify both the plugin and the effective sandbox:

apus plugins inspect openshell --runtime --json
apus sandbox list
apus sandbox explain
openshell sandbox list

apus sandbox list is empty until a sandboxed agent turn first needs a runtime.

Workspace modes

This is the most important OpenShell decision.

OpenShell also has a control-plane resource named a workspace. That is separate from the filesystem workspace described below: it scopes sandboxes, providers, policies, inference routes, and membership. Set plugins.entries.openshell.config.workspace to use an existing non-default OpenShell workspace. The plugin does not create OpenShell workspaces or manage their membership. When this setting is unset, the plugin preserves the OpenShell CLI's ambient OPENSHELL_WORKSPACE selection, or the CLI's default fallback when no ambient selection exists.

mirror (default)

plugins.entries.openshell.config.mode: "mirror" keeps the local workspace canonical:

• Before exec, Apus syncs the local workspace into the sandbox.
• After exec, Apus syncs the remote workspace back to local.
• Within one Apus Gateway process, commands and file-tool operations sharing a workspace wait for the current operation to finish. The lock covers the complete upload, command, and download, or the complete file read/mutation and its synchronization. Separate backend handles share the same lock.
• File tools go through the sandbox bridge, but local stays source of truth between turns.
• Working-directory checks inspect the host directories that will be uploaded and release their lock before returning. Execution owns its own complete upload-to-download operation. An abandoned check cannot block later tools. Remote permissions and image-specific restrictions are checked when execution starts.

Best for development workflows: local edits outside Apus show up on the next exec, and the sandbox behaves close to the Docker backend.

Tradeoff: upload + download cost on every exec turn.

External editors and other Gateway processes do not participate in that lock. Avoid changing the local workspace while a mirrored command is running, because its download can replace those external edits.

remote

mode: "remote" makes the remote workspace canonical:

• On first use after sandbox creation, Apus seeds the remote workspace from local once. If the Gateway restarts before that first use, the next use detects the still-empty remote workspace and seeds it. A remote workspace that already holds content is never re-seeded.
• After that, exec, read, write, edit, and apply_patch operate directly on the remote workspace. Apus does not sync remote changes back to local.
• Initialization is serialized per remote runtime, but commands and file tools can overlap after initialization, including across agent turns. A background command can therefore wait for a file written by a later turn. Concurrent writes to the same file follow normal remote filesystem semantics.
• Materialized skills refresh when a backend initializes for a turn, rather than before every filesystem operation. As with other sandbox backends, a later turn can refresh skills while older background commands are running.
• Prompt-time media reads still work (file/media tools read through the sandbox bridge).
• Outbound images and other attachments can use paths under the configured remote workspace, such as /sandbox/chart.png.

Best for long-running agents and CI: lower per-turn overhead, and host-local edits cannot silently clobber remote state.

Choosing a mode

Configuration reference

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

remoteWorkspaceDir and remoteAgentWorkspaceDir must be absolute paths and stay under the managed roots /sandbox or /agent. Other absolute paths are rejected. Choose distinct, non-overlapping directories because Apus manages their contents independently. Previously configured overlapping roots remain accepted for upgrade compatibility.

timeoutSeconds applies to ordinary OpenShell CLI operations. Sandbox creation always receives at least 300 seconds so image builds and first-time provisioning are not cut short by the default 120-second command timeout.

policy is a file path, not a policy name or ID. Prefer an absolute path such as /etc/apus/openshell-policy.yaml. Relative paths are resolved from the agent's local workspace during sandbox creation. An explicit policy overrides the OpenShell CLI's OPENSHELL_SANDBOX_POLICY environment variable. When neither is set, OpenShell uses its normal policy selection and defaults.

providers names existing OpenShell credential providers in the selected OpenShell workspace. With autoProviders: true, OpenShell may create missing providers from credentials already available to the Gateway process. With autoProviders: false, create required providers first and verify them with openshell --workspace <workspace-name> provider list. Keep API keys in OpenShell providers rather than adding them to sandbox environment variables.

workspace must match OpenShell's current workspace-name contract: 1-19 lowercase alphanumeric characters or single hyphens, with no leading, trailing, or consecutive hyphen. Create it first with openshell workspace create --name <name>. OpenShell rejects sandbox operations when the selected workspace does not exist or is being deleted. Set it to "default" to override an ambient non-default OpenShell workspace explicitly.

The setting applies to every OpenShell sandbox managed by this plugin instance. It cannot select different OpenShell workspaces per Apus agent or session. Changing it does not migrate existing sandboxes. Delete Apus's OpenShell sandboxes while the old workspace is still configured, then change the setting and restart the Gateway.

Sandbox-level settings (mode, scope, workspaceAccess) live under agents.defaults.sandbox like any backend. See Sandboxing for the full matrix.

To pass non-secret environment values into sandboxed commands, use the existing agents.defaults.sandbox.docker.env setting. The OpenShell backend also applies those values during command execution. OpenShell does not currently inject them into sandbox creation or background services. Keep credentials in OpenShell providers or another dedicated secret-delivery mechanism.

Examples

Minimal remote setup

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

Mirror mode with GPU

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

Per-agent OpenShell with custom gateway

{
  agents: {
    defaults: {
      sandbox: { mode: "off" },
    },
    entries: {
      researcher: {
        sandbox: {
          mode: "all",
          backend: "openshell",
          scope: "agent",
          workspaceAccess: "rw",
        },
      },
    },
  },
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          from: "apus",
          mode: "remote",
          gateway: "lab",
          gatewayEndpoint: "https://lab.example",
          workspace: "research",
          policy: "/etc/apus/openshell-policy.yaml",
        },
      },
    },
  },
}

Lifecycle management

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

# Inspect effective policy
apus sandbox explain

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

# Recreate only one agent or the exact session scope shown by sandbox list
apus sandbox recreate --agent researcher
apus sandbox recreate --session "agent:researcher:main"

For remote mode, recreate is especially important: it deletes the canonical remote workspace for that scope, and the next use seeds a fresh one from local. For mirror mode, recreate mainly resets the remote execution environment since local stays canonical.

Sandbox list and recreate commands activate the configured backend's owning plugin plus the owner of each recorded runtime before inspecting or deleting it. Unrelated plugins are not loaded for these operations, and browser-only commands remain independent of the OpenShell backend.

Apus keeps a registered sandbox's shipped legacy runtime name after an upgrade so its remote workspace remains addressable. Recreating that scope deletes the legacy runtime. The next use creates the current 19-character runtime name.

OpenShell v0.0.92 can still locate a sandbox record created by v0.0.68, but a Docker-backed sandbox may remain in a non-Ready phase after the gateway upgrade. Apus preserves the registered runtime identity, refuses to create a replacement implicitly, and reports the scoped apus sandbox recreate command. Treat that recreation as destructive in remote mode because the remote workspace is canonical.

Recreate after changing any of:

• agents.defaults.sandbox.backend
• plugins.entries.openshell.config.from
• plugins.entries.openshell.config.mode
• plugins.entries.openshell.config.policy
• plugins.entries.openshell.config.providers, gpu, or autoProviders
• plugins.entries.openshell.config.remoteWorkspaceDir or remoteAgentWorkspaceDir

When changing the OpenShell gateway or OpenShell workspace, recreate the affected sandboxes while the old gateway and workspace are still selected. Otherwise cleanup targets the new location instead of the existing sandbox.

If OpenShell cannot delete a sandbox, Apus reports the failure and keeps the runtime registry entry so recreation or pruning can be retried safely. Restore the original gateway, workspace, authentication, and connectivity, inspect the runtime with openshell --workspace <workspace-name> sandbox get <sandbox-name>, and rerun the scoped apus sandbox recreate command. Do not switch the configured workspace or delete the registry entry to hide the failure.

Security hardening

The mirror-mode filesystem bridge pins the local workspace root and rechecks canonical paths (via realpath) before every read, write, mkdir, remove, and rename, rejecting mid-path symlinks. A symlink swap or a remounted local workspace cannot redirect file access outside the mirrored tree.

Workspace synchronization excludes .git, hooks, and git-hooks in both directions. Repository credentials, history, and trusted hook code remain on the Apus Gateway host instead of being copied into an untrusted sandbox.

Mirror synchronization never copies entries it cannot represent, such as symlinks, FIFOs, or Unix sockets, into either workspace. Existing host entries of those types remain intact at every depth, along with their parent directories, even if the sandbox deletes those directories or replaces them with files. Remote replacements that conflict with these preserved host paths are ignored. Ordinary files and directories still receive remote changes and deletions.

Local filesystem inspection errors, such as permission or I/O failures, stop the affected synchronization instead of treating the path as missing. Fix the reported filesystem error before retrying; materialized skills are inspected before the existing remote skills view is cleared.

Custom image contract

The OpenShell source image owns the remote operating system and package set. Apus does not apply Docker image, root-filesystem, network, user, or package settings to this backend.

Custom images used with the Apus filesystem bridge must provide:

• /bin/sh
• sleep for the persistent sandbox main process, when the OpenShell CLI supports detached sandbox creation (sandbox create --detach)
• python3 for pinned remote filesystem reads and mutations
• GNU-compatible stat (-c), readlink (-f), and find
• standard mkdir, mv, rm, and rmdir utilities

When the agent workspace differs from the sandbox workspace, the sandbox user and policy also need write access to both configured remote roots. Standard unprivileged images often cannot create the default /agent directory. Either create and grant access to /agent in the image and policy, or configure two non-overlapping directories beneath the already-writable sandbox root:

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          remoteWorkspaceDir: "/sandbox/workspace",
          remoteAgentWorkspaceDir: "/sandbox/agent",
        },
      },
    },
  },
}

Package installation and private certificate roots must be included in the source image or installed from inside the sandbox. The selected OpenShell policy must permit the required network destinations, and the sandbox user and filesystem must permit the writes. sandbox.docker.network, sandbox.docker.readOnlyRoot, sandbox.docker.user, and sandbox.docker.setupCommand do not configure OpenShell.

Current limitations

• Sandbox browser is not supported on the OpenShell backend.
• One plugin instance uses one OpenShell workspace. Per-agent or per-session OpenShell workspace selection is not supported.
• sandbox.docker.binds does not apply to OpenShell. Sandbox creation fails if binds are configured.
• Docker-specific runtime knobs under sandbox.docker.* (other than env) apply only to the Docker backend.
• Native plugin code and Gateway RPC stay on the Gateway host. Plugin-owned and MCP tools are available to sandboxed sessions only when sandbox tool policy allows them.

Troubleshooting

First separate Apus Gateway health, plugin activation, and OpenShell gateway connectivity:

apus gateway status --deep --require-rpc
apus plugins inspect openshell --runtime --json
apus sandbox explain
apus sandbox list
openshell gateway list
openshell sandbox list
apus logs --follow

• Plugin missing or backend unavailable: Install @openclaw/openshell-sandbox, set plugins.entries.openshell.enabled: true, validate the config, and restart the Apus Gateway. Run apus plugins inspect openshell --runtime --json to check the running Gateway rather than only the on-disk plugin registration.
• openshell not found: Install the CLI for the user running the Gateway, or set plugins.entries.openshell.config.command to its absolute executable path. A working interactive shell does not prove the managed service has the same PATH.
• No active gateway, unauthorized, or connection failed: Check openshell gateway list, select the intended gateway, and reauthenticate with openshell gateway login <gateway-name> when its deployment requires login. Set plugins.entries.openshell.config.gateway explicitly when the service should not depend on the interactive CLI's active selection.
• Workspace missing or the wrong sandbox list: Verify the selected OpenShell workspace with openshell workspace list, then run openshell --workspace <workspace-name> sandbox list. Create missing workspaces with openshell workspace create --name <workspace-name> before enabling them in Apus. Remember that the Gateway service may not inherit OPENSHELL_WORKSPACE from your interactive shell.
• Policy file cannot be read or outbound traffic is denied: Configure an existing YAML policy file using an absolute host path, check its permissions, and verify that the policy permits the destination and requesting binary. Inspect a running sandbox with openshell sandbox get <sandbox-name> --policy-only. Docker network settings do not change OpenShell policy.
• Provider creation fails: Inspect the selected OpenShell workspace with openshell provider list, then create or refresh the required provider using OpenShell's documented credential flow. If autoProviders is disabled, required providers must already exist.
• Remote files are missing locally: This is expected in remote mode. Remote files are canonical and are not synchronized back to the host. Use mirror mode when host-visible changes are required. Recreating a remote sandbox destroys its remote-only files.
• An image or attachment cannot be sent: Use a path under the configured remoteWorkspaceDir, such as /sandbox/report.png, rather than assuming every backend uses Docker's /workspace directory.
• Mirror synchronization reports recovery paths: Apus kept a host shadow outside the workspace because its move or restoration could not finish. The error identifies the preserved path and the workspace path and retains the original failure. Compare both paths and recover the needed files before deleting either copy. A partial move can leave different files in each path. Apus preserves remaining workspace entries instead of overwriting them with an incomplete or unverified backup. If restoration completed and only cleanup of the preservation directory failed, the error confirms the restored workspace path and identifies the leftover directory instead.
• Recreate or prune cannot delete a sandbox: Restore access to the original OpenShell gateway and workspace, confirm the sandbox still exists with openshell --workspace <workspace-name> sandbox get <sandbox-name>, and retry the scoped recreation. Apus retains the registry entry until deletion succeeds.

How it works

1. Apus runs sandbox get for the sandbox name (with the selected OpenShell workspace and any configured --gateway/--gateway-endpoint). If that fails it creates one in the same OpenShell workspace with sandbox create, passing --name, --from, --policy when set, --gpu when enabled, --auto-providers/--no-auto-providers, and one --provider flag per configured provider.
2. Apus runs sandbox ssh-config for the sandbox name to fetch SSH connection details.
3. Core writes the SSH config to a temp file and opens an SSH session through the same remote filesystem bridge as the generic SSH backend.
4. In mirror mode: sync local to remote before exec, run, sync back after.
5. In remote mode: seed once on first use, 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 - apus sandbox commands