Agent Sandboxing#

Introduction#

Sandboxing separates an agent’s tool execution from the host environment and limits the files and network endpoints available to it. Agent Harness Installer provides this capability through OpenShell for OpenClaw, Hermes and Deep Agents Code. This integration targets OpenShell 0.1.5 on Linux with Docker; host mode remains the default.

The --runtime option is not mandatory. Interactive installation offers host or openshell, with Enter selecting host. Non-interactive installation uses host mode unless --runtime openshell or HARNESS_RUNTIME=openshell is set. The commands below select OpenShell explicitly for reproducible setup.

This is one layer of Agentic AI Security, not prompt protection or PII masking. A sandbox can still perform unwanted actions within its permitted workspace and allowed services. Review tool effects, protect credentials and grant only the access needed for a task.

Architecture and security boundaries#

        flowchart LR
    classDef client fill:#F3F3F3,stroke:#777,color:#222
    classDef sandbox fill:#EAF7EE,stroke:#2E7D32,color:#123D17
    classDef service fill:#EAF3FB,stroke:#0068B5,color:#0A2A43
    classDef store fill:#FFF6DD,stroke:#B38600,color:#4A3900
    classDef boundary fill:#FFF6DD,stroke:#B38600,color:#4A3900,stroke-dasharray:5 5

    USER["User workstation<br/>CLI or browser"]:::client
    FORWARD["OpenShell forwarding<br/>and SSH tunnel<br/>loopback only"]:::client

    subgraph HOST["Linux host"]
        direction LR
        GATEWAY["OpenShell local gateway<br/>sandbox lifecycle and policy"]:::service

        subgraph BOX["OpenShell sandbox · non-root"]
            direction TB
            AGENT["OpenClaw, Hermes<br/>or Deep Agents Code"]:::sandbox
            TOOLS["Agent tools and workspace<br/>sandbox filesystem policy"]:::sandbox
            AGENT --> TOOLS
        end

        subgraph INFERENCE["Shared inference · host loopback publication"]
            direction LR
            IR["Inference Router<br/>127.0.0.1:8010"]:::service
            subgraph BACKEND["Private Docker backend network"]
                direction LR
                OVMS["OpenVINO Model Server"]:::service
                MODEL[("Selected model<br/>GPU when available")]:::store
                OVMS --> MODEL
            end
            IR --> OVMS
        end

        EXT["Optional external inference endpoint<br/>configured on IR"]:::client
        IR -. "when externally configured" .-> EXT
    end

    USER -->|"OpenShell CLI"| AGENT
    USER -->|"OpenClaw UI or Hermes dashboard<br/>on-demand, forwarded privately"| FORWARD
    FORWARD --> AGENT
    GATEWAY -. "creates and controls sandbox" .-> BOX
    AGENT -->|"Attached provider<br/>host.openshell.internal:8010/v1"| IR

    WEB["Web search, external browsing,<br/>MCP and messaging services"]:::boundary
    AGENT -. "not permitted by default;<br/>requires additional policy" .-> WEB
    

Each agent has an independently owned profile under ~/.agent-harness-install/openshell/<agent>/. All installed sandboxes use shared inference. Existing host agent configuration is not imported or modified during sandbox installation. External inference is configured on shared IR using HARNESS_LLM_ROUTER_ENDPOINT, not directly in the sandbox; in that case IR routes to the external backend instead of managed OVMS.

Host mode already publishes IR/OVMS on loopback by default and connects them through a private Docker backend network. OpenShell reuses that architecture and additionally enforces loopback-only publication, validating actual service bindings and the managed backend network before attaching a sandbox. Host-mode LAN-publication options remain available; they are not supported in OpenShell mode.

Sandbox images install the same pinned agent packages/installers as host mode, run as a non-root user and do not mount host agent homes, model directories or the Docker socket. Runtime egress is limited to the attached inference provider. Web search, external browsing, MCP, package downloads, updates and messaging need explicit additional policy and any required tool dependencies/credentials. Working LLM inference does not establish external web-tool connectivity. The host mcp/skill helpers reject OpenShell mode rather than modifying the wrong agent.

OpenShell applies Landlock with best_effort compatibility; enforcement may vary with the host kernel. Desktop/computer-use workflows are not enabled.

Prerequisites#

  • Linux with Docker and sufficient memory/disk for the chosen model and images.

  • OpenShell 0.1.5. A different installed version is rejected rather than upgraded or downgraded automatically.

  • Automatic OpenShell CLI/gateway provisioning requires Debian/Ubuntu and a working systemd user service. On other Linux distributions, install and configure OpenShell 0.1.5 manually before running the installer.

  • Host Node.js is required for installer configuration/profile handling. The installer runs its normal host prerequisite setup.

  • Network access for initial package/image/model downloads, or suitable caches. Runtime sandbox egress restrictions do not describe the image-build environment.

HARNESS_OPENSHELL_GATEWAY selects the gateway when creating a new profile (default: openshell); lifecycle commands use the recorded gateway. On a fresh machine the checksum-pinned upstream installer provisions the CLI and local gateway. Existing gateways must already be configured and authenticated.

See Get Started for general installer prerequisites. Run the commands below from the Agent Harness Installer component directory.

Getting started#

Default sandbox setup#

The installer supplies sandbox policies, inference-provider configuration and agent-specific model configuration as a functional starting point. No initial policy authoring is required, but the prerequisites above still apply.

  • Filesystem policy: OpenClaw uses the base agent policy. Hermes and Deep Agents Code use the interactive policy, which also permits sandbox-local pseudo-terminal devices for their terminal interfaces. The policies allow writes to the sandbox home, /sandbox, /tmp and /dev/null; they do not mount the host home or Docker socket.

  • Inference access: A separate attached provider policy permits access to the shared Inference Router. This is not general internet access: web search, external browsing, MCP and messaging require additional policy, dependencies and credentials as appropriate.

  • Model and configuration: Fresh managed OpenShell deployments default to OpenVINO/Qwen3.5-9B-int8-ov with the default openvino model hub only when no explicit or reusable selection exists. Saved selections and explicit model, hub and exporter choices take precedence. OpenClaw and Hermes receive the supported Qwen tuning defaults; Deep Agents Code receives provider/model configuration, not those same tuning settings.

These defaults apply to sandbox deployments. Host-mode model selection is unchanged, and an external inference backend does not receive the fresh managed model fallback. Default policies remain subject to the security limitations described above; a working inference connection is not a guarantee of tool-use correctness.

Customize a sandbox policy#

Start with the least privilege needed by your agent. The installer selects openshell/policy.yaml for OpenClaw and openshell/interactive-policy.yaml for Hermes and Deep Agents Code. The interactive policy adds sandbox-local PTY device access required by those agents. Keep inference-provider access separate from filesystem permissions; adding filesystem paths does not grant network access.

Static customization before installation#

Edit the policy file in your checked-out frameworks/agent-harness-install directory before provisioning. Modify openshell/policy.yaml for OpenClaw or openshell/interactive-policy.yaml for Hermes and Deep Agents Code, then run the normal installer command for that agent. For example:

# Edit the policy file for the selected agent, then:
./install.sh --runtime openshell --harness hermes --non-interactive

This changes the policy supplied when a sandbox is created. Re-running the installer does not replace an already-owned sandbox or update its policy. To recreate an existing sandbox from the edited file, first back up any workspace data you need, then remove only that agent’s sandbox and install it again:

./uninstall.sh --runtime openshell --harness hermes --sandbox-only --yes
./install.sh --runtime openshell --harness hermes --non-interactive

Use the matching --harness value for your agent. Sandbox removal deletes its sandbox state; do not use this recreation path unless you have backed up data you need to keep.

Dynamic policy changes#

Use OpenShell commands to change a running sandbox’s network access. For example, the following grants only curl read-only access to the GitHub API; replace the sandbox name, gateway and binary with values for your setup:

SANDBOX_NAME=ahi-0123456789ab
GATEWAY_NAME=openshell
openshell policy update "$SANDBOX_NAME" \
  --rule-name github_readonly \
  --binary /usr/bin/curl \
  --add-endpoint api.github.com:443:read-only:rest:enforce \
  --wait --gateway "$GATEWAY_NAME"
openshell policy get "$SANDBOX_NAME" --gateway "$GATEWAY_NAME" --full
openshell policy list "$SANDBOX_NAME" --gateway "$GATEWAY_NAME"

policy update incrementally changes network endpoints/rules, and network rules take effect while the sandbox is running. --wait waits for the sandbox to report whether it loaded the new revision; policy get --full shows the effective policy and policy list shows revision status. Verify the intended request from inside the sandbox as well. This example changes one sandbox; do not use a gateway-global policy unless you intend to change all sandboxes.

For complete policy YAML changes, first save the current base policy so the replacement retains paths and rules OpenShell already added:

openshell policy get "$SANDBOX_NAME" --gateway "$GATEWAY_NAME" \
  --base --output json | jq -e '.policy' > ./custom-policy.json
# Edit ./custom-policy.json, then:
openshell policy set "$SANDBOX_NAME" --policy ./custom-policy.json \
  --gateway "$GATEWAY_NAME" --wait

policy set replaces the complete base policy. Network sections take effect live, but filesystem_policy, Landlock and process settings take effect only when a sandbox starts. Adding filesystem paths does not grant access to an already-running workload; removed paths and other startup-only changes may be rejected. To apply filesystem changes, back up needed data, then recreate the sandbox using the static customization steps above. See NVIDIA OpenShell’s policy schema reference, policy management guide and live network policy tutorial for YAML semantics, lifecycle and additional examples. These links match the OpenShell 0.1.5 CLI pinned by this installer.

The prepared-runner integration suite validates both workflows against a live sandbox: its static boundary case checks workspace read/write plus allowed and denied network requests; its dynamic-policy case checks that a live network rule changes the request result without breaking filesystem access, and that removing the rule restores network access. See the live integration test catalogue.

Install a sandboxed agent#

On a fresh host, one command provisions installer-owned OVMS and IR, downloads OpenVINO/Qwen3.5-9B-int8-ov, and installs OpenClaw in its sandbox:

./install.sh --runtime openshell --harness openclaw --non-interactive

For Hermes, use:

./install.sh --runtime openshell --harness hermes --non-interactive

For Deep Agents Code, use:

./install.sh --runtime openshell --harness deepagents-code --non-interactive

Run one command to install one agent, or multiple commands to create separate sandboxes against the same shared model. The default is the 9B model in the Qwen3.5 family, not a 3.5B model. Explicit --model, exporter and hub choices remain supported; host-mode model selection is unchanged.

The default model’s preconverted OpenVINO weights are downloaded using the existing hf-snapshot exporter. Its repository has no OVMS graph, so the pinned serving image generates graph.pbtxt using --configure --task text_generation before registration. Once the serving image is available, this metadata-only container step needs no network/GPU access and does not reconvert weights. No external OVMS container or local model-directory import is used.

With managed local inference, IR/OVMS are validated for the exact model, readiness, private network and loopback publication. With an external backend, the local IR’s loopback publication and advertised model are checked instead; the installer does not manage that external backend. An installed sandbox’s OpenShell workspace is recorded with its ownership profile and reused for later lifecycle and cleanup commands. Set OPENSHELL_WORKSPACE before the first install to select a non-default workspace. The Inference Router port is also recorded by the sandbox provider; changing HARNESS_IR_PORT for an existing sandbox is rejected rather than leaving its network policy pointed at a stale endpoint; a port change requires a complete OpenShell teardown and reinstall.

To prepare or explicitly reconfigure shared inference separately:

./install.sh inference --runtime openshell --non-interactive
# Or choose another model explicitly:
./install.sh inference --runtime openshell --model <model-id> --non-interactive

Separate inference provisioning is optional, not a prerequisite for a fresh managed sandbox install.

Inspect and connect#

./install.sh status --runtime openshell --harness openclaw
./install.sh connect --runtime openshell --harness openclaw

For Hermes:

./install.sh status --runtime openshell --harness hermes
./install.sh connect --runtime openshell --harness hermes

For Deep Agents Code:

./install.sh status --runtime openshell --harness deepagents-code
./install.sh connect --runtime openshell --harness deepagents-code

The OpenShell gateway owns sandbox lifecycle and policy delivery. The OpenClaw gateway runs inside its sandbox, binds to sandbox loopback and uses a generated authentication token. Hermes and Deep Agents Code run as interactive terminal chat interfaces; messaging integrations are not enabled. Dcode’s interactive interface is a terminal UI, not a hosted browser UI. From a local machine, open an SSH session with a PTY (for example, ssh -t user@<host>), then run the Dcode connect command above. It forces a PTY for the sandbox session so the chat interface can receive input and render interactively. Deep Agents Code is configured with the shared OpenAI-compatible inference endpoint and the selected local model as its default, so no model selection is needed. The connector skips Dcode’s first-run setup; Tavily web search remains unconfigured unless the user supplies an API key later. connect supplies the non-secret HARNESS_DCODE_API_KEY=not-needed placeholder only to the Dcode process; it is not stored in the sandbox environment. connect uses OpenShell’s authenticated execution path and does not publish an agent UI on the LAN. The connector disables Dcode’s optional Wasmtime-backed JavaScript interpreter, avoiding a nested execution runtime; the OpenShell sandbox remains the execution boundary for agent work.

Browser access#

Agent UIs must remain private: use OpenShell forwarding bound to host loopback and an SSH tunnel to your laptop rather than LAN publication.

Hermes browser chat is available on demand through its built-in dashboard: run hermes dashboard --host 127.0.0.1 --port 9119 --skip-build --no-open inside the owned sandbox using openshell sandbox exec. Forward sandbox port 9119 with openshell forward service, then SSH-tunnel the host loopback port to your laptop. The dashboard is not started by the installer and stops with its process/sandbox; keep its launcher running during testing. No messaging gateway is required for browser chat. Do not expose the loopback-only dashboard on a LAN without configuring Hermes authentication. This browser UI is separate from external web-search/browser tools: those tools still need explicit egress policy and any required service configuration.

For example, read the sandbox name and gateway from ~/.agent-harness-install/openshell/hermes/profile.json. Substitute them below. Run the dashboard on the installation host in one terminal:

openshell sandbox exec --name <sandbox-name> --no-tty --no-login-shell \
  -g <gateway-name> -- /home/node/.local/bin/hermes dashboard \
  --host 127.0.0.1 --port 9119 --skip-build --no-open

In a second terminal on that host, keep the forward running:

openshell forward service <sandbox-name> --target-port 9119 \
  --local 127.0.0.1:19119 -g <gateway-name>

On your laptop, substitute your SSH account/host and add your SSH identity option if needed:

ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:19119:127.0.0.1:19119 <user>@<installation-host>

Open http://127.0.0.1:19119/chat?profile=default on the laptop. The example uses loopback/tunnel access and does not require an OpenClaw token. A Hermes “Gateway Status: Off” indication refers to its messaging gateway, not a failed browser dashboard. Stop all three commands when finished.

Hermes and Deep Agents Code use an interactive policy matching the base agent policy except for writable /dev/ptmx and /dev/pts. These sandbox-local pseudo-terminal devices are needed by their terminal interfaces; OpenClaw’s policy is unchanged. This does not grant host filesystem, Docker socket or additional network access. Existing sandboxes must be recreated with the new policy after backing up needed data.

Model lifecycle and repeated installs#

Repeated installs without --model reuse the saved shared model and preserve sandbox data. The full source ID, hub, exporter, revision and conversion options are saved in ~/.agent-harness-install/openshell-model-source.json; the served ID is also recorded in openshell-model. Older installations fall back to their shared selection, agent profile or OVMS registry before the fresh-install default.

An explicit new --model checks the normal exporter cache, downloads/converts when needed, reconfigures OVMS/IR, and synchronizes all installed sandbox agents. Changing shared inference can interrupt active turns: finish those turns first. The installer preserves sandbox identities, gateway tokens, history and workspace. It writes a durable selection inside each sandbox, restarts it without deletion, and updates its host profile only after the restart/model check succeeds. The durable selection takes precedence over the original sandbox creation environment, so OpenClaw and Hermes keep the new model on later stop/start.

An interrupted switch leaves openshell-model-pending.json; rerun the install without --model to resume that exact target before requesting another model. This is recoverable sequencing, not an atomic all-service transaction: a failed switch may temporarily leave inference or an agent unavailable. Old downloaded models remain cached until full uninstall. Only the selected model remains registered for serving in managed OpenShell mode, avoiding simultaneous loading of previous large models into GPU memory. A no-model rerun does not silently replace an existing route; incomplete deployments require an explicit model selection to repair.

Existing images predating restart-safe startup fail preflight before inference is modified. They require a separately planned image migration after backing up needed data; the installer does not automate image upgrades, agent replacement or backup/restore and never deletes/recreates a legacy sandbox to change its model.

Qwen local-model defaults#

New OpenShell images generate a responsiveness-oriented baseline for the exact served model Qwen3.5-9B-int8-ov:

Setting

OpenClaw

Hermes

Deep Agents Code

Context budget

contextWindow: 65536

model.context_length: 65536

Agent default; no additional context override

Reply cap

Catalog and model params maxTokens: 4096

Custom-provider extra_body.max_tokens: 4096

Managed provider max_tokens: 4096

Sampling

Model params temperature: 0.2

Custom-provider extra_body.temperature: 0.2

Managed provider temperature: 0.2

Thinking

thinkingDefault: off and chat_template_kwargs.enable_thinking: false

Model reasoning override none and custom-provider chat_template_kwargs.enable_thinking: false

Managed provider chat_template_kwargs.enable_thinking: false

Prompt/tool size

localModelLean: true, bootstrap limits 4000/12000 characters, tools.profile: coding

No unsupported OpenClaw prompt/tool settings are copied

No agent-specific prompt/tool overrides

These are operational budgets, not model maximum capabilities or latency guarantees. The previous 512-token cap could truncate answers and tool calls; the default is now 4096 and can be tuned for the model and workload. Existing explicit settings, including catalog values in older configurations, take precedence; absent keys receive defaults. Startup preserves gateway tokens, history and workspace data. Hermes uses its bundled Python/YAML runtime and a dedicated custom:harness-ovms-qwen provider through the same IR endpoint. Deep Agents Code receives equivalent Qwen request tuning in its installer-managed OpenAI-compatible provider block.

The sandbox’s .harness-local-defaults.json tracks only installer-added values. Restarts preserve user edits. Switching models removes unchanged installer-added Qwen values before configuring the next model; user overrides remain. Other models keep existing settings, or the previous generic OpenClaw catalog defaults (32768 context / 4096 output) when none exist. Host mode is unchanged. Existing images need rebuilding/migration to include this startup behavior; this is not a live deployment migration or a chat acceptance gate.

Validation and troubleshooting#

Onboarding checks inference connectivity, not agentic correctness. A Ready sandbox or successful chat smoke test does not validate multi-step tool use. Tool-use acceptance requires independently verifying generated files/content. The 0.5B quickstart model is not a validated multi-step tool-use baseline.

Symptom

Check

LLM responds but web search or browsing fails

External tools need explicit egress policy and service configuration; IR only supplies inference routing

Hermes dashboard opens but its terminal cannot allocate a PTY

Use the Hermes-specific policy; older sandboxes need backed-up recreation

OpenClaw SQLite temporary-storage errors

Current startup exports a private mode-700 SQLITE_TMPDIR before any Node process; older images need the updated startup

Installation reports a pending model transition

Rerun without --model to resume before selecting a different model

Offline regression tests: bash test/openshell-test.sh. Agent-image build and real sandbox tests require Docker, the pinned gateway and a running shared IR. See OpenShell quality gates for automated test cases, TAP reports, opt-in lifecycle tests and CI runner setup. PTY allocation tests are not automated browser chat acceptance tests.

Uninstall#

Back up needed chat/workspace data before uninstalling. Full uninstall deletes all installer-owned sandboxes, shared IR, managed OVMS, downloaded models and installer state by default. An installer-owned OpenShell CLI/gateway is removed; a pre-existing installation is preserved. An external inference backend is never removed. If the same state directory records a host-installed agent, full uninstall removes that agent too.

Use the uninstall guide for full/scoped commands, ownership safeguards, retained prerequisites and the --keep-models option. Stop separately launched forwarding and SSH processes after uninstall.

See Known Limitations for remaining runtime, model, network and migration restrictions.