# How it works ## Host-mode install flow `./install.sh` is the only command you run. It prepares the host, brings up the inference backend, installs the chosen agent, and wires the two together. The diagram below describes host mode; OpenShell's automatic model selection, sandbox lifecycle and onboarding are covered in the [Agent Sandboxing guide](./agentic-ai-security/agent-sandboxing.md). ```mermaid %%{init: {"flowchart": {"wrappingWidth": 420, "nodeSpacing": 40, "rankSpacing": 45, "curve": "basis"}}}%% flowchart TD classDef step fill:#EAF3FB,stroke:#0068B5,color:#0A2A43 classDef decision fill:#FFF6DD,stroke:#B38600,color:#4A3900 classDef agent fill:#EAF7EE,stroke:#2E7D32,color:#123D17 classDef done fill:#0068B5,stroke:#0068B5,color:#FFFFFF START(["./install.sh [--harness agent] --model id"]):::step CO{"Run from a
source checkout?"}:::decision CLONE["Fetch the pinned
HARNESS_INSTALL_REF
into a temp dir"]:::step PAYLOAD["scripts/install.sh"]:::step START --> CO CO -- "yes" --> PAYLOAD CO -- "no, standalone" --> CLONE --> PAYLOAD subgraph PREP["Host preparation"] direction TB STARTUP["startup.sh
curl and git, Docker, Node.js via nvm,
Python venv and PyYAML"]:::step GPU["Intel GPU check
driver, /dev/dri render nodes, compute runtime
no GPU: continues CPU-only"]:::step STARTUP --> GPU end PAYLOAD --> STARTUP subgraph S1["Step 1 of 3: Inference routing"] direction TB EXT{"External router
endpoint set?"}:::decision OVMS["Start OpenVINO Model Server
Docker, GPU via --device"]:::step EXPORT["Fetch --model from its hub (default: Hugging Face,
converted to OpenVINO IR) and register it
with OVMS when it has a graph.pbtxt"]:::step IR["Pull and start the Inference Router
intel/inference-router, in front of OVMS
or of the external endpoint"]:::step EXT -- "yes (OVMS is not started)" --> IR EXT -- "no" --> OVMS --> EXPORT --> IR end GPU --> EXT subgraph S2["Step 2 of 3: Agent install"] direction TB PICK{"HARNESS_AGENT"}:::decision OC["OpenClaw
npm install -g"]:::agent DC["Deep Agents Code
dcode installer"]:::agent HM["Hermes
official installer"]:::agent PICK --> OC PICK --> DC PICK --> HM end IR --> PICK subgraph S3["Step 3 of 3: Onboarding"] direction TB ONB["Point the agent at the endpoint
OpenClaw and dcode: configure and smoke-test
Hermes: print the endpoint to configure"]:::step end OC --> ONB DC --> ONB HM --> ONB FINISH(["Installation complete"]):::done ONB --> FINISH ``` Third-party downloads (the Hermes and dcode installers, Docker's convenience script) are fetched over HTTPS and verified against a SHA-256 before they run. The Hermes and dcode installers come from pinned upstream commits with their digests built in, so no flags are needed; the Docker convenience script still needs a digest or an explicit opt-out. ## Runtime architecture Once installed, the agent talks to a single OpenAI-compatible endpoint. The Inference Router sits in front of OVMS (or of an external endpoint), and the local containers run on a dedicated Docker network. Published ports bind to 127.0.0.1 by default; set `HARNESS_ADVERTISED_HOST` (a specific address) or `HARNESS_BIND_HOST=0.0.0.0` (all interfaces) to reach them from other machines. These LAN-publication overrides apply only to host mode; OpenShell mode reuses the existing loopback publication and private backend network, but requires inference ports to remain bound to `127.0.0.1` and validates the running deployment's bindings and, for managed OVMS, backend network. The diagram below shows the host-mode agent, not an OpenShell sandbox. Neither service authenticates inbound requests, and Docker-published ports bypass `ufw`, so restrict access with the `DOCKER-USER` iptables chain or bind to a specific interface address. ```mermaid %%{init: {"flowchart": {"wrappingWidth": 420, "nodeSpacing": 40, "rankSpacing": 60, "curve": "basis"}}}%% flowchart TD classDef host fill:#EAF3FB,stroke:#0068B5,color:#0A2A43 classDef box fill:#FFFFFF,stroke:#0068B5,color:#0A2A43 classDef store fill:#FFF6DD,stroke:#B38600,color:#4A3900 classDef hw fill:#EAF7EE,stroke:#2E7D32,color:#123D17 classDef ext fill:#F3F3F3,stroke:#777777,color:#222222,stroke-dasharray: 4 3 subgraph HOST["Intel host: Core Ultra iGPU or Arc, or CPU-only"] direction TB AGENT["Agent CLI
OpenClaw, Deep Agents Code, or Hermes"]:::box subgraph NET["Docker network: agent-harness-install-backend"] direction TB IRC["Inference Router
#lt;host-ip#gt;:8010/v1"]:::box OVMSC["OpenVINO Model Server
#lt;host-ip#gt;:8000/v3"]:::box end MODELS[("OpenVINO models
~/.agent-harness-install/models")]:::store GPUD["Intel GPU
/dev/dri render nodes"]:::hw end EXTR["External OpenAI-compatible endpoint
HARNESS_LLM_ROUTER_ENDPOINT"]:::ext REMOTE["Other machines on the network
optional"]:::ext AGENT -- "OpenAI-compatible API
host-ip is 127.0.0.1 by default" --> IRC IRC -- "container name" --> OVMSC OVMSC --- MODELS OVMSC -. "--device and --group-add" .-> GPUD IRC -. "or, when HARNESS_LLM_ROUTER_ENDPOINT is set" .-> EXTR REMOTE -. "only when HARNESS_ADVERTISED_HOST or HARNESS_BIND_HOST is set" .-> IRC class HOST host ``` ## OpenShell sandbox runtime For OpenShell, the agent runs in its own non-root sandbox. The attached inference provider grants access to IR; managed IR-to-OVMS traffic stays on a private Docker network. Agent UI access is forwarded privately on demand. See the [Agent Sandboxing guide](./agentic-ai-security/agent-sandboxing.md) for setup and security details. ```mermaid %%{init: {"flowchart": {"wrappingWidth": 420, "nodeSpacing": 40, "rankSpacing": 60, "curve": "basis"}}}%% flowchart TD classDef host fill:#EAF3FB,stroke:#0068B5,color:#0A2A43 classDef box fill:#FFFFFF,stroke:#0068B5,color:#0A2A43 classDef agent fill:#EAF7EE,stroke:#2E7D32,color:#123D17 classDef store fill:#FFF6DD,stroke:#B38600,color:#4A3900 classDef ext fill:#F3F3F3,stroke:#777777,color:#222222,stroke-dasharray:4 3 USER["User workstation
OpenShell CLI or privately forwarded UI"]:::ext subgraph HOST["Linux host"] direction TB subgraph SANDBOX["OpenShell sandbox: non-root agent"] direction TB AGENT["OpenClaw or Hermes"]:::agent TOOLS["Agent tools and workspace
sandbox filesystem policy"]:::box AGENT --> TOOLS end GATEWAY["OpenShell gateway
lifecycle and policy control"]:::box subgraph INFERENCE["Shared inference: host loopback"] direction LR IR["Inference Router
127.0.0.1:8010"]:::box subgraph BACKEND["Private Docker network"] direction LR OVMS["OpenVINO Model Server"]:::box MODEL[("Selected model
GPU when available")]:::store OVMS --> MODEL end IR --> OVMS end end EXTERNAL["External inference endpoint
optional route configured on IR"]:::ext EGRESS["Web search, browsing, MCP
additional policy required"]:::ext USER -->|"OpenShell connect or UI tunnel"| AGENT GATEWAY -. "creates and controls" .-> SANDBOX AGENT -->|"Attached provider
host.openshell.internal:8010/v1"| IR IR -. "when externally configured" .-> EXTERNAL AGENT -. "not allowed by default" .-> EGRESS ```