# 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](../agentic-ai-security.md), 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
```mermaid
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
CLI or browser"]:::client
FORWARD["OpenShell forwarding
and SSH tunnel
loopback only"]:::client
subgraph HOST["Linux host"]
direction LR
GATEWAY["OpenShell local gateway
sandbox lifecycle and policy"]:::service
subgraph BOX["OpenShell sandbox · non-root"]
direction TB
AGENT["OpenClaw, Hermes
or Deep Agents Code"]:::sandbox
TOOLS["Agent tools and workspace
sandbox filesystem policy"]:::sandbox
AGENT --> TOOLS
end
subgraph INFERENCE["Shared inference · host loopback publication"]
direction LR
IR["Inference Router
127.0.0.1:8010"]:::service
subgraph BACKEND["Private Docker backend network"]
direction LR
OVMS["OpenVINO Model Server"]:::service
MODEL[("Selected model
GPU when available")]:::store
OVMS --> MODEL
end
IR --> OVMS
end
EXT["Optional external inference endpoint
configured on IR"]:::client
IR -. "when externally configured" .-> EXT
end
USER -->|"OpenShell CLI"| AGENT
USER -->|"OpenClaw UI or Hermes dashboard
on-demand, forwarded privately"| FORWARD
FORWARD --> AGENT
GATEWAY -. "creates and controls sandbox" .-> BOX
AGENT -->|"Attached provider
host.openshell.internal:8010/v1"| IR
WEB["Web search, external browsing,
MCP and messaging services"]:::boundary
AGENT -. "not permitted by default;
requires additional policy" .-> WEB
```
Each agent has an independently owned profile under
`~/.agent-harness-install/openshell//`. 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](../get-started.md) 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](../../../openshell/policy.yaml).
Hermes and Deep Agents Code use the [interactive policy](../../../openshell/interactive-policy.yaml),
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](#qwen-local-model-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:
```bash
# 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:
```bash
./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:
```bash
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:
```bash
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](https://docs.nvidia.com/openshell/v0.1.5/how-it-works/policies/schema),
[policy management guide](https://docs.nvidia.com/openshell/v0.1.5/how-it-works/policies/manage-policies)
and [live network policy tutorial](https://docs.nvidia.com/openshell/v0.1.5/tutorials/first-network-policy)
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](../../../test/integration-tests.md#individual-cases-and-objectives).
### 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:
```bash
./install.sh --runtime openshell --harness openclaw --non-interactive
```
For Hermes, use:
```bash
./install.sh --runtime openshell --harness hermes --non-interactive
```
For Deep Agents Code, use:
```bash
./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:
```bash
./install.sh inference --runtime openshell --non-interactive
# Or choose another model explicitly:
./install.sh inference --runtime openshell --model --non-interactive
```
Separate inference provisioning is optional, not a prerequisite for a fresh
managed sandbox install.
### Inspect and connect
```bash
./install.sh status --runtime openshell --harness openclaw
./install.sh connect --runtime openshell --harness openclaw
```
For Hermes:
```bash
./install.sh status --runtime openshell --harness hermes
./install.sh connect --runtime openshell --harness hermes
```
For Deep Agents Code:
```bash
./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@`),
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:
```bash
openshell sandbox exec --name --no-tty --no-login-shell \
-g -- /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:
```bash
openshell forward service --target-port 9119 \
--local 127.0.0.1:19119 -g
```
On your laptop, substitute your SSH account/host and add your SSH identity
option if needed:
```text
ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 -L 127.0.0.1:19119:127.0.0.1:19119 @
```
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](../../../openshell/interactive-policy.yaml)
matching the [base agent policy](../../../openshell/policy.yaml) 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](../../../test/README.md) 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](../get-started/uninstall.md#openshell-profiles) 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](../known-limitations.md) for remaining
runtime, model, network and migration restrictions.