# Known Limitations For sandbox setup, architecture and lifecycle guidance, see [Agent Sandboxing](./agentic-ai-security/agent-sandboxing.md), part of [Agentic AI Security](./agentic-ai-security.md). - The OpenShell integration currently targets Linux with Docker, OpenShell 0.1.5 and OpenClaw/Hermes. Each agent has one independently owned profile; both use shared, loopback-published inference. A fresh OpenShell install automatically provisions managed OVMS/IR and defaults to `Qwen3.5-9B-int8-ov`. Separate inference provisioning is optional: `./install.sh inference --runtime openshell --model --non-interactive`. Host Node.js is still required for installer configuration handling. Automatic OpenShell CLI/gateway provisioning requires Debian/Ubuntu with a working systemd user service; other Linux distributions require a manually installed and configured OpenShell 0.1.5. - Repeated installs without `--model` preserve the saved model selection and sandbox data rather than silently replacing existing routes. An explicit new `--model` reuses cached files or downloads/converts as needed, reconfigures shared inference and synchronizes both installed agents. This can interrupt active turns. Interrupted changes are recoverable by rerunning without `--model`, but are not atomic across services. Older sandbox images without restart-safe model support are rejected before inference is changed. - Sandbox runtime network access initially permits only the attached shared IR endpoint. Web search, external browsing/downloads, package updates, messaging and MCP integrations require explicit additional network policy and any necessary tool dependencies or 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. - The Hermes messaging gateway is not enabled. Its built-in browser dashboard can run without that gateway, using the Hermes-specific PTY policy and loopback forwarding. The installer does not start the dashboard automatically. Existing Hermes sandboxes need recreation with the new policy to gain this PTY access; back up needed data first. - Automatic agent replacement, legacy-image migration and backup/restore workflows are not provided. Normal model changes and sandbox stop/start are supported; they are not image upgrades or migration of host agent data. - A sandbox's Ready state or successful chat smoke test does not validate multi-step tool use. Check actual tool effects and exact output contents. - The pinned Hermes installer optionally downloads a computer-use driver. Its availability depends on image libraries and upstream installer behavior; this integration does not enable or validate desktop/computer-use workflows. - The Inference Router matches the requested model name exactly against the served name, and the served name drops the Hugging Face organisation (`org/name` is served as `name`). A client configured with `org/name` gets `Unknown model`. Streamed requests are still answered with HTTP 200 and carry the error in the response body, so the failure is easy to miss in client logs. Configure clients with the name `/v1/models` returns. - Host-mode OpenClaw onboarding registers the inference endpoint as a custom model provider (`openclaw config set models.providers.ovms ...`, OpenClaw's own documented `models.providers` mechanism — see docs/gateway/config-tools/custom-providers.md in github.com/openclaw/openclaw), selects it with `openclaw models set`, and smoke-tests it with `openclaw infer model run` — the same shape as the dcode/Hermes onboarding paths. This requires OpenClaw's local Gateway daemon to be stopped (its own `config set` refuses to write otherwise); on a fresh install there is no daemon running yet, so this only matters when re-running `./install.sh onboard` after `openclaw gateway run`/ `openclaw onboard --install-daemon` has started one — stop it first, or configure the provider manually with the command the warning prints. OpenClaw is installed via `npm install -g openclaw` rather than its own `curl | bash` installer intentionally — that installer exists for people who do not want to manage Node.js themselves, but Agent Harness Installer deliberately manages Node.js (via nvm) itself, consistently across all three agents; using OpenClaw's own installer too would mean two separate, possibly-conflicting Node.js runtimes. `npm install -g` is OpenClaw's own documented path for environments that already manage Node.js. - "Hermes" installs via its own official installer (curl | bash), not npm — this installer downloads and runs it unattended (`--skip-setup --non-interactive`). Nous Research does not publish a checksum for it, and the `hermes-agent.nousresearch.com` URL always serves the latest script, so this installer instead fetches `scripts/install.sh` from a pinned `NousResearch/hermes-agent` commit (the `v0.22.2` tag), verifies its SHA-256, and passes the same commit via `--commit`. No flags are needed. To use a different installer, set `HERMES_INSTALL_URL` together with `HERMES_INSTALL_SHA256` (or `HERMES_ALLOW_UNVERIFIED_INSTALL=1`, not recommended); `HERMES_INSTALL_SHA256` alone overrides the built-in digest. - "deepagents-code" installs LangChain's official `dcode` CLI via its own installer. As with Hermes, this installer fetches `libs/code/scripts/install.sh` from a pinned `langchain-ai/deepagents` commit (the `deepagents-code==0.1.86` tag, byte-identical to what `https://langch.in/dcode` served for that release), verifies its SHA-256 and installs that exact dcode version. Override with `DEEPAGENTS_CODE_VERSION`, or use a different installer via `DCODE_INSTALL_URL` plus `DCODE_INSTALL_SHA256` (or `HARNESS_ALLOW_UNVERIFIED_DCODE_INSTALL=1`). It is wired to OVMS by writing a `[models.providers.openai]` block into `~/.deepagents/config.toml` (dcode's own "Compatible APIs" mechanism) inside `BEGIN`/`END` markers, so a re-run replaces only that block and leaves any other provider config alone — but a config.toml a user already hand-edited to use a *different* `openai` provider block (outside those markers) would end up with two. The managed block reads its API key from `HARNESS_DCODE_API_KEY`, which only the installer's own smoke test sets; running `dcode` yourself needs `export HARNESS_DCODE_API_KEY=not-needed` (any non-empty value; the local endpoint ignores it) or it fails with `MissingCredentialsError`. Behind a corporate proxy, dcode's local LangGraph health check is also sent through the proxy and rejected (`Server did not become healthy within 60s (last status: 403)`), because many HTTP clients ignore `localhost` and CIDR entries in `no_proxy` for `127.0.0.1`. Run it without the proxy variables: `env -u http_proxy -u https_proxy -u HTTP_PROXY -u HTTPS_PROXY dcode ...`. - Intel's Core Ultra iGPU/Arc lineup has no fixed appliance concept, so there is no dual-node pairing/reboot-resume receipt handling. - Model export (`optimum-cli export openvino`) is CPU/host-bound and can be slow for large models. - OVMS runs as the fixed UID 5000 and must read the models directory. After each export or download the installer runs `chmod -R o+rX` on it, so models created under a restrictive umask (for example `077`) are still loadable. The step is skipped, with a warning, if the directory resolves to `/`, `$HOME` or a parent of `$HOME`, and files owned by another user are reported with the `sudo chmod` to run. - `./install.sh models ...` and `onboard` need Node.js. When `node` is not on `PATH` (for example a non-login shell), they load nvm and select `HARNESS_NODE_VERSION`. If Node.js is still missing, `models` warns that results may be incomplete; run `./startup.sh --skip-docker --skip-python` to install it. - `mcp register` has Hermes's config shape and OpenClaw's `mcp set` command built in; other agents need `HARNESS_MCP_REGISTER_CMD` set to a real registration script. - `HARNESS_OVMS_EXPORTER` normally defaults to `docker-pull` (the OpenShell Qwen3.5 default uses `hf-snapshot` instead), which runs OVMS's own "-py" Docker image (bundles `optimum-cli`) in `--pull` mode to download, convert, and quantize a `--model` entirely via Docker — no host Python venv, no separate GitHub-fetched script. Three alternatives remain for hosts that need them: - `export-model-py` — the original host-venv-based exporter: fetches and pins OVMS's `export_model.py`/`requirements.txt` from GitHub, runs them in a Python venv. Kept for hosts that cannot or will not run the conversion step inside Docker. - `model-download` — runs edge-ai-libraries' Model Download microservice as a one-shot ephemeral container (`get_model.sh`) instead. Newer and less battle-tested than the other two. Its Docker image also defaults to the floating `latest` tag unless `HARNESS_MODEL_DOWNLOAD_IMAGE_TAG` is pinned, and its `get_model.sh` is fetched from a pinned commit and verified against a built-in SHA-256 (a different `HARNESS_MODEL_DOWNLOAD_SCRIPT_REF` needs its own `HARNESS_MODEL_DOWNLOAD_SCRIPT_SHA256`, or `HARNESS_ALLOW_UNVERIFIED_MODEL_DOWNLOAD_SCRIPT=1`). `get_model.sh` converts with its own OVMS release (default `v2025.4.1`), which may differ from the OVMS image served here; set `HARNESS_MODEL_DOWNLOAD_OVMS_RELEASE_TAG` to pass `--ovms-release-tag`. For gated Hugging Face models, export `HF_TOKEN`. It is also what `--model-hub` selects: any hub other than the default `openvino` chooses this exporter automatically (unless `HARNESS_OVMS_EXPORTER` is set to something else, which is then rejected as a conflict). The hubs are the microservice's own: `openvino` (Hugging Face + conversion, the default), `huggingface` (raw download), `ollama`, `remote-url`, `ultralytics`, `geti`, `pipeline-zoo-models`, `omz` and `hls`. A download is registered with OVMS, and wired to the Inference Router, only when it contains a `graph.pbtxt` — the `openvino` hub always produces one, a pre-converted `huggingface` repo or a `remote-url` tarball may, and the other hubs never can (Ollama-format models are not loadable by OVMS yet; Ultralytics, Geti, the zoos and HLS are vision/other-runtime models, not something an agent can use). Whatever is not served is still downloaded and tracked (`/unregistered-downloads.json`), so it shows up under `./install.sh models list` (labeled "not served by OVMS") and can be removed with `./install.sh models remove ` even though `config.json` never gets an entry for it. Which hubs can be served is decided in one place, `model_hub_unserved_reason` in `scripts/lib/openvino.sh`, so Ollama can be enabled there once OVMS supports it. `--model` is validated per hub before anything is installed (for example `org/name` for Hugging Face, `name[:tag]` for Ollama, a URL in `--model-config` for `remote-url`, `GETI_*` for Geti). `--model-type` (default `llm` for `openvino`/`huggingface`), `--model-revision`, `--model-precision` (default `int8`), `--model-device` (default `CPU`), `--model-config` and `HARNESS_MODEL_PLUGINS` mirror `get_model.sh`'s own `--type`/`--revision`/`--precision`/`--device`/`--config-json`/`--plugins` flags (the matching `HARNESS_MODEL_*` environment variables work too) — see microservices/model-download/docs/user-guide/get-started.md in edge-ai-libraries for the full parameter reference per hub. Other exporters ignore the options that do not apply to them and say so (`--model-precision` also applies to the default `docker-pull` and the `export-model-py` exporters, except for pre-converted `OpenVINO/*` models, which are already quantized; `--model-revision` also to `hf-snapshot`). - `hf-snapshot` — a plain `huggingface_hub.snapshot_download` in a host Python venv, no `optimum-cli` conversion step at all. For HF repos already published as ready-to-serve OpenVINO IR + an OVMS MediaPipe `graph.pbtxt`. Set `HARNESS_HF_MODEL_REVISION` to pin an exact commit/tag. The exact repository `OpenVINO/Qwen3.5-9B-int8-ov` is supported even though it omits `graph.pbtxt`: the serving image generates its text-generation graph with `--configure` after download, without reconverting weights. Other snapshot repositories must already include `graph.pbtxt`; a missing graph fails installation. This exporter does not convert raw/un-exported model weights. All four register the resulting model into `config.json` the same way (a `model_config_list` entry — confirmed by comparing exporters' output side by side; OVMS itself auto-detects the `graph.pbtxt` sitting in `base_path`) whenever they produce one. `model-download` registers a download only if it contains a `graph.pbtxt` (see above). - With the default `docker-pull` exporter, if a model's `generation_config.json` does not list the tokenizer's `eos_token` id in `eos_token_id` (for example `OpenVINO/Qwen3.5-9B-int4-ov` omits `<|im_end|>`, so OVMS never stops generating), the installer adds it, on fresh pulls and on re-runs. Reasoning models can spend several hundred tokens thinking before the answer, so a small `max_tokens` may return an empty reply. - The **Inference Router** (IR) always sits in front of the model backend and is what agents are actually wired to (`harness_llm_endpoint`) — not optional, including when `HARNESS_LLM_ROUTER_ENDPOINT` points at an external endpoint (IR's provider is then that endpoint instead of OVMS; `HARNESS_LLM_ROUTER_API_KEY` is sent as a bearer token, and a `localhost`/`127.0.0.1` endpoint is unreachable from inside the IR container, so use the host's LAN address or `host.docker.internal`). This installer pulls the published `intel/inference-router` image (`HARNESS_IR_IMAGE`, default tag `2026.2.0`). That image is a release build and may not match the pinned source commit below exactly; set `HARNESS_IR_BUILD_FROM_SOURCE=1` to build it locally from a pinned commit SHA of `microservices/inference-router` in `open-edge-platform/edge-ai-libraries` instead (`HARNESS_IR_SOURCE_REPO`/`HARNESS_IR_SOURCE_REF`; a full 40-character SHA is required unless `HARNESS_ALLOW_UNVERIFIED_IR_SOURCE=1`). IR limits concurrent requests (3 by default) and answers `429` above that. IR's `providers[].type` is passed straight through to LiteLLM as a `type/model` prefix with no allowlist enforced by IR's own config loader; `HARNESS_IR_PROVIDER_TYPE` defaults to `hosted_vllm` (the type IR's own examples use for a self-hosted OpenAI-compatible backend). `openai` does not work here: LiteLLM's `openai` provider requires an API key, so every request to the keyless OVMS fails with "Missing credentials". - IR's routing policy defaults to `Balanced` (single provider, no extra GPU-resident classifier model) — confirmed against IR's own `RouterOrchestrator`/`DecisionEngine.from_config`/bundled `policy.yaml` that `Balanced` only instantiates its own strategies (`Planning`/`ContextLengthQuality`), never the classifier-backed `IntelligentRouting` strategy. `HARNESS_IR_ROUTING_POLICY=Intelligent` is **not actually usable with this installer today**: that policy needs an OpenVINO classifier model mounted at `/models/ov-classifier` (IR's own `IR_OV_MODEL` env var/volume), which this installer never prepares, downloads, or mounts — selecting `Intelligent` as-is will very likely make IR fail at startup. Treat this override as a placeholder for future work, not a supported option, until the classifier model is wired up. Shares the GPU with OVMS (confirmed acceptable); `HARNESS_IR_PORT` defaults to `8010` to avoid colliding with OVMS's own `8000`. - OVMS and the Inference Router are joined to a dedicated Docker network (`HARNESS_BACKEND_NETWORK`, default `agent-harness-install-backend`) so IR can reach OVMS by container name on OVMS's internal port — IR runs in its own container and cannot reach OVMS via the install host's loopback/advertised address or a host-published port that is bound loopback-only by default (`resolve_bind_host`). Both containers are recreated (not just restarted) on host-mode installs when they already exist, so a container from an older version of this installer (before this network existed) picks it up automatically, along with any other changed GPU/proxy/port configuration, on the next host-mode run. OpenShell installs reuse healthy existing inference on a no-model rerun; an explicit `--model` or pending model transition triggers reconfiguration. - Published ports of OVMS (`8000`) and the Inference Router (`8010`) bind to `127.0.0.1` by default. `HARNESS_ADVERTISED_HOST=` binds them to that address and prints it in endpoint URLs; `HARNESS_BIND_HOST=0.0.0.0` binds all interfaces but does not change the printed URLs, so set `HARNESS_ADVERTISED_HOST` as well (or use the machine's real address). Neither service authenticates inbound requests, and Docker-published ports bypass `ufw`; restrict access with the `DOCKER-USER` iptables chain or bind to a specific interface. These LAN-publication overrides apply to host mode; OpenShell mode requires inference publication on `127.0.0.1`. Only the advertised host is persisted (`~/.agent-harness-install/advertised-host`); `HARNESS_BIND_HOST` must be set again on every run. Binding a specific address requires it to exist on the host: an address that is not assigned yet (for example a DHCP lease that arrives after Docker starts at boot) stops the container from starting. - Switching from a locally-managed OVMS install to `HARNESS_LLM_ROUTER_ENDPOINT` does not stop/remove the previously-managed OVMS container: re-running `ensure_inference_backend` with the router endpoint set only updates the `ovms-managed` marker and restarts the Inference Router against the new provider; it never calls `remove_openvino_model_server`. The Router is always removed by `./uninstall.sh`, but OVMS is skipped once the marker says the last install routed externally, so that earlier OVMS container (and its image) must be removed manually: `docker rm -f agent-harness-install-ovms`, or re-run `./install.sh` without the router endpoint and then `./uninstall.sh`. - `HARNESS_OVMS_IMAGE` (the serving image, default `2026.4.1-gpu`) and `HARNESS_OVMS_EXPORT_IMAGE` (the "-py" image the default `docker-pull` exporter converts models with, default `2026.1-py`) are pinned separately because OVMS has not published a newer "-py" tag. Pre-converted `OpenVINO/*` models need no conversion, so they are pulled with the serving image itself and the two always match. Any other model is converted by an older OVMS than the one that serves it; this pairing is only exercised by `test/full-flow-test.sh` on real hardware. - Host mode has no fresh-install default model: a full install needs `--model` (or `HARNESS_HF_MODEL`), prompted for on a terminal and an error otherwise, unless a model is already exported from an earlier run. OpenShell mode instead reuses its saved selection or defaults to `Qwen3.5-9B-int8-ov` for a fresh managed deployment. With `HARNESS_LLM_ROUTER_ENDPOINT`, `--model`/`HARNESS_LLM_MODEL` names the model the external endpoint serves. - Docker, Node.js/npm, and Python (venv + PyYAML) are installed/verified by `./startup.sh`, which `./install.sh` now runs automatically as its first step (see [Get Started](./get-started.md)) — there is still only one script to run. `test/full-flow-test.sh` and `test/smoke-test.sh` also call it explicitly up front (so an early prerequisite failure is reported before the long per-agent install loop, not buried inside it); running either test script directly still assumes a host that can reach the package repositories/URLs `./startup.sh` itself downloads from.