Known Limitations#

For sandbox setup, architecture and lifecycle guidance, see Agent Sandboxing, part of Agentic AI Security.

  • 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 <model-id> --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 (<models-dir>/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 <name> 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=<ip> 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) — 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.