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,/tmpand/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-ovwith the defaultopenvinomodel 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 |
|
|
Agent default; no additional context override |
Reply cap |
Catalog and model params |
Custom-provider |
Managed provider |
Sampling |
Model params |
Custom-provider |
Managed provider |
Thinking |
|
Model reasoning override |
Managed provider |
Prompt/tool size |
|
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 |
Installation reports a pending model transition |
Rerun without |
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.