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
--modelpreserve the saved model selection and sandbox data rather than silently replacing existing routes. An explicit new--modelreuses 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/skillhelpers 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/nameis served asname). A client configured withorg/namegetsUnknown 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/modelsreturns.Host-mode OpenClaw onboarding registers the inference endpoint as a custom model provider (
openclaw config set models.providers.ovms ..., OpenClaw’s own documentedmodels.providersmechanism — see docs/gateway/config-tools/custom-providers.md in github.com/openclaw/openclaw), selects it withopenclaw models set, and smoke-tests it withopenclaw infer model run— the same shape as the dcode/Hermes onboarding paths. This requires OpenClaw’s local Gateway daemon to be stopped (its ownconfig setrefuses to write otherwise); on a fresh install there is no daemon running yet, so this only matters when re-running./install.sh onboardafteropenclaw gateway run/openclaw onboard --install-daemonhas started one — stop it first, or configure the provider manually with the command the warning prints. OpenClaw is installed vianpm install -g openclawrather than its owncurl | bashinstaller 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 -gis 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 thehermes-agent.nousresearch.comURL always serves the latest script, so this installer instead fetchesscripts/install.shfrom a pinnedNousResearch/hermes-agentcommit (thev0.22.2tag), verifies its SHA-256, and passes the same commit via--commit. No flags are needed. To use a different installer, setHERMES_INSTALL_URLtogether withHERMES_INSTALL_SHA256(orHERMES_ALLOW_UNVERIFIED_INSTALL=1, not recommended);HERMES_INSTALL_SHA256alone overrides the built-in digest.“deepagents-code” installs LangChain’s official
dcodeCLI via its own installer. As with Hermes, this installer fetcheslibs/code/scripts/install.shfrom a pinnedlangchain-ai/deepagentscommit (thedeepagents-code==0.1.86tag, byte-identical to whathttps://langch.in/dcodeserved for that release), verifies its SHA-256 and installs that exact dcode version. Override withDEEPAGENTS_CODE_VERSION, or use a different installer viaDCODE_INSTALL_URLplusDCODE_INSTALL_SHA256(orHARNESS_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) insideBEGIN/ENDmarkers, 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 differentopenaiprovider block (outside those markers) would end up with two. The managed block reads its API key fromHARNESS_DCODE_API_KEY, which only the installer’s own smoke test sets; runningdcodeyourself needsexport HARNESS_DCODE_API_KEY=not-needed(any non-empty value; the local endpoint ignores it) or it fails withMissingCredentialsError. 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 ignorelocalhostand CIDR entries inno_proxyfor127.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+rXon it, so models created under a restrictive umask (for example077) are still loadable. The step is skipped, with a warning, if the directory resolves to/,$HOMEor a parent of$HOME, and files owned by another user are reported with thesudo chmodto run../install.sh models ...andonboardneed Node.js. Whennodeis not onPATH(for example a non-login shell), they load nvm and selectHARNESS_NODE_VERSION. If Node.js is still missing,modelswarns that results may be incomplete; run./startup.sh --skip-docker --skip-pythonto install it.mcp registerhas Hermes’s config shape and OpenClaw’smcp setcommand built in; other agents needHARNESS_MCP_REGISTER_CMDset to a real registration script.HARNESS_OVMS_EXPORTERnormally defaults todocker-pull(the OpenShell Qwen3.5 default useshf-snapshotinstead), which runs OVMS’s own “-py” Docker image (bundlesoptimum-cli) in--pullmode to download, convert, and quantize a--modelentirely 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’sexport_model.py/requirements.txtfrom 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 floatinglatesttag unlessHARNESS_MODEL_DOWNLOAD_IMAGE_TAGis pinned, and itsget_model.shis fetched from a pinned commit and verified against a built-in SHA-256 (a differentHARNESS_MODEL_DOWNLOAD_SCRIPT_REFneeds its ownHARNESS_MODEL_DOWNLOAD_SCRIPT_SHA256, orHARNESS_ALLOW_UNVERIFIED_MODEL_DOWNLOAD_SCRIPT=1).get_model.shconverts with its own OVMS release (defaultv2025.4.1), which may differ from the OVMS image served here; setHARNESS_MODEL_DOWNLOAD_OVMS_RELEASE_TAGto pass--ovms-release-tag. For gated Hugging Face models, exportHF_TOKEN. It is also what--model-hubselects: any hub other than the defaultopenvinochooses this exporter automatically (unlessHARNESS_OVMS_EXPORTERis 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,omzandhls. A download is registered with OVMS, and wired to the Inference Router, only when it contains agraph.pbtxt— theopenvinohub always produces one, a pre-convertedhuggingfacerepo or aremote-urltarball 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 thoughconfig.jsonnever gets an entry for it. Which hubs can be served is decided in one place,model_hub_unserved_reasoninscripts/lib/openvino.sh, so Ollama can be enabled there once OVMS supports it.--modelis validated per hub before anything is installed (for exampleorg/namefor Hugging Face,name[:tag]for Ollama, a URL in--model-configforremote-url,GETI_*for Geti).--model-type(defaultllmforopenvino/huggingface),--model-revision,--model-precision(defaultint8),--model-device(defaultCPU),--model-configandHARNESS_MODEL_PLUGINSmirrorget_model.sh’s own--type/--revision/--precision/--device/--config-json/--pluginsflags (the matchingHARNESS_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-precisionalso applies to the defaultdocker-pulland theexport-model-pyexporters, except for pre-convertedOpenVINO/*models, which are already quantized;--model-revisionalso tohf-snapshot).hf-snapshot— a plainhuggingface_hub.snapshot_downloadin a host Python venv, nooptimum-cliconversion step at all. For HF repos already published as ready-to-serve OpenVINO IR + an OVMS MediaPipegraph.pbtxt. SetHARNESS_HF_MODEL_REVISIONto pin an exact commit/tag. The exact repositoryOpenVINO/Qwen3.5-9B-int8-ovis supported even though it omitsgraph.pbtxt: the serving image generates its text-generation graph with--configureafter download, without reconverting weights. Other snapshot repositories must already includegraph.pbtxt; a missing graph fails installation. This exporter does not convert raw/un-exported model weights.
All four register the resulting model into
config.jsonthe same way (amodel_config_listentry — confirmed by comparing exporters’ output side by side; OVMS itself auto-detects thegraph.pbtxtsitting inbase_path) whenever they produce one.model-downloadregisters a download only if it contains agraph.pbtxt(see above).With the default
docker-pullexporter, if a model’sgeneration_config.jsondoes not list the tokenizer’seos_tokenid ineos_token_id(for exampleOpenVINO/Qwen3.5-9B-int4-ovomits<|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 smallmax_tokensmay 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 whenHARNESS_LLM_ROUTER_ENDPOINTpoints at an external endpoint (IR’s provider is then that endpoint instead of OVMS;HARNESS_LLM_ROUTER_API_KEYis sent as a bearer token, and alocalhost/127.0.0.1endpoint is unreachable from inside the IR container, so use the host’s LAN address orhost.docker.internal). This installer pulls the publishedintel/inference-routerimage (HARNESS_IR_IMAGE, default tag2026.2.0). That image is a release build and may not match the pinned source commit below exactly; setHARNESS_IR_BUILD_FROM_SOURCE=1to build it locally from a pinned commit SHA ofmicroservices/inference-routerinopen-edge-platform/edge-ai-librariesinstead (HARNESS_IR_SOURCE_REPO/HARNESS_IR_SOURCE_REF; a full 40-character SHA is required unlessHARNESS_ALLOW_UNVERIFIED_IR_SOURCE=1). IR limits concurrent requests (3 by default) and answers429above that. IR’sproviders[].typeis passed straight through to LiteLLM as atype/modelprefix with no allowlist enforced by IR’s own config loader;HARNESS_IR_PROVIDER_TYPEdefaults tohosted_vllm(the type IR’s own examples use for a self-hosted OpenAI-compatible backend).openaidoes not work here: LiteLLM’sopenaiprovider 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 ownRouterOrchestrator/DecisionEngine.from_config/bundledpolicy.yamlthatBalancedonly instantiates its own strategies (Planning/ContextLengthQuality), never the classifier-backedIntelligentRoutingstrategy.HARNESS_IR_ROUTING_POLICY=Intelligentis not actually usable with this installer today: that policy needs an OpenVINO classifier model mounted at/models/ov-classifier(IR’s ownIR_OV_MODELenv var/volume), which this installer never prepares, downloads, or mounts — selectingIntelligentas-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_PORTdefaults to8010to avoid colliding with OVMS’s own8000.OVMS and the Inference Router are joined to a dedicated Docker network (
HARNESS_BACKEND_NETWORK, defaultagent-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--modelor pending model transition triggers reconfiguration.Published ports of OVMS (
8000) and the Inference Router (8010) bind to127.0.0.1by default.HARNESS_ADVERTISED_HOST=<ip>binds them to that address and prints it in endpoint URLs;HARNESS_BIND_HOST=0.0.0.0binds all interfaces but does not change the printed URLs, so setHARNESS_ADVERTISED_HOSTas well (or use the machine’s real address). Neither service authenticates inbound requests, and Docker-published ports bypassufw; restrict access with theDOCKER-USERiptables chain or bind to a specific interface. These LAN-publication overrides apply to host mode; OpenShell mode requires inference publication on127.0.0.1. Only the advertised host is persisted (~/.agent-harness-install/advertised-host);HARNESS_BIND_HOSTmust 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_ENDPOINTdoes not stop/remove the previously-managed OVMS container: re-runningensure_inference_backendwith the router endpoint set only updates theovms-managedmarker and restarts the Inference Router against the new provider; it never callsremove_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.shwithout the router endpoint and then./uninstall.sh.HARNESS_OVMS_IMAGE(the serving image, default2026.4.1-gpu) andHARNESS_OVMS_EXPORT_IMAGE(the “-py” image the defaultdocker-pullexporter converts models with, default2026.1-py) are pinned separately because OVMS has not published a newer “-py” tag. Pre-convertedOpenVINO/*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 bytest/full-flow-test.shon real hardware.Host mode has no fresh-install default model: a full install needs
--model(orHARNESS_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 toQwen3.5-9B-int8-ovfor a fresh managed deployment. WithHARNESS_LLM_ROUTER_ENDPOINT,--model/HARNESS_LLM_MODELnames the model the external endpoint serves.Docker, Node.js/npm, and Python (venv + PyYAML) are installed/verified by
./startup.sh, which./install.shnow runs automatically as its first step (see Get Started) — there is still only one script to run.test/full-flow-test.shandtest/smoke-test.shalso 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.shitself downloads from.