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.

        %%{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<br/>source checkout?"}:::decision
    CLONE["Fetch the pinned<br/>HARNESS_INSTALL_REF<br/>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<br/>curl and git, Docker, Node.js via nvm,<br/>Python venv and PyYAML"]:::step
        GPU["Intel GPU check<br/>driver, /dev/dri render nodes, compute runtime<br/>no GPU: continues CPU-only"]:::step
        STARTUP --> GPU
    end
    PAYLOAD --> STARTUP

    subgraph S1["Step 1 of 3: Inference routing"]
        direction TB
        EXT{"External router<br/>endpoint set?"}:::decision
        OVMS["Start OpenVINO Model Server<br/>Docker, GPU via --device"]:::step
        EXPORT["Fetch --model from its hub (default: Hugging Face,<br/>converted to OpenVINO IR) and register it<br/>with OVMS when it has a graph.pbtxt"]:::step
        IR["Pull and start the Inference Router<br/>intel/inference-router, in front of OVMS<br/>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<br/>npm install -g"]:::agent
        DC["Deep Agents Code<br/>dcode installer"]:::agent
        HM["Hermes<br/>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<br/>OpenClaw and dcode: configure and smoke-test<br/>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.

        %%{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<br/>OpenClaw, Deep Agents Code, or Hermes"]:::box
        subgraph NET["Docker network: agent-harness-install-backend"]
            direction TB
            IRC["Inference Router<br/>#lt;host-ip#gt;:8010/v1"]:::box
            OVMSC["OpenVINO Model Server<br/>#lt;host-ip#gt;:8000/v3"]:::box
        end
        MODELS[("OpenVINO models<br/>~/.agent-harness-install/models")]:::store
        GPUD["Intel GPU<br/>/dev/dri render nodes"]:::hw
    end
    EXTR["External OpenAI-compatible endpoint<br/>HARNESS_LLM_ROUTER_ENDPOINT"]:::ext
    REMOTE["Other machines on the network<br/>optional"]:::ext

    AGENT -- "OpenAI-compatible API<br/>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 for setup and security details.

        %%{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<br/>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<br/>sandbox filesystem policy"]:::box
            AGENT --> TOOLS
        end
        GATEWAY["OpenShell gateway<br/>lifecycle and policy control"]:::box

        subgraph INFERENCE["Shared inference: host loopback"]
            direction LR
            IR["Inference Router<br/>127.0.0.1:8010"]:::box
            subgraph BACKEND["Private Docker network"]
                direction LR
                OVMS["OpenVINO Model Server"]:::box
                MODEL[("Selected model<br/>GPU when available")]:::store
                OVMS --> MODEL
            end
            IR --> OVMS
        end
    end

    EXTERNAL["External inference endpoint<br/>optional route configured on IR"]:::ext
    EGRESS["Web search, browsing, MCP<br/>additional policy required"]:::ext

    USER -->|"OpenShell connect or UI tunnel"| AGENT
    GATEWAY -. "creates and controls" .-> SANDBOX
    AGENT -->|"Attached provider<br/>host.openshell.internal:8010/v1"| IR
    IR -. "when externally configured" .-> EXTERNAL
    AGENT -. "not allowed by default" .-> EGRESS