Hugpy Harness

Connect to either a standalone wrapper or a basic Core fleet endpoint with hugpy-harness --base http://host:port. The harness displays fleet resource snapshots per worker, including stale/offline state. Conversations remain in the same local workspace journal when changing endpoints.

Optional standalone terminal interface for a local or remote Hugpy wrapper. No dependency on hugpy-agent or the hugpy-wrapper Python package. Communication uses HTTP; no background service, engine installation or worker enrollment.

Install

Build with bash packaging/debian/build.sh. The output directory contains the harness .deb, a separate wrapper .deb when its local build is available, and install.sh. Distribute these together for installation without an APT repository (system Python packages must still be available).

cd build/debian
./install.sh                         # missing local wrapper: prompt [Y/n]
./install.sh --yes                   # default yes without prompts
./install.sh --without-wrapper       # harness only, e.g. remote wrapper
./install.sh --dry-run               # show APT plan without changing packages

A compatible installed wrapper is reused. The installer checks all required local package files before calling APT. Noninteractive default is yes; use --without-wrapper explicitly for a remote-only client.

The .deb declares the wrapper as Recommends, so standard APT installations include it by default when a repository provides it. It is optional, not a hard dependency. For the current local release use install.sh, which passes the separate wrapper package to APT when needed. Alternatively:

sudo apt install ./hugpy-wrapper_0.1.62_all.deb ./hugpy-harness_0.1.1_all.deb
sudo apt install --no-install-recommends ./hugpy-harness_0.1.1_all.deb

The harness runtime is /opt/hugpy-harness/venv; the wrapper retains its own runtime and service. Neither package embeds the other. Installing the wrapper alone does not install the harness.

Launch

hugpy-harness
hugpy-harness launch --workspace /path/to/project
hugpy-harness --base http://HOST:PORT --workspace /path/to/project
hugpy-harness chat --model MODEL_ID

A local endpoint is discovered from the wrapper endpoint file. Remote access uses --base and HUGPY_WRAPPER_API_KEY when authentication is required. hugpy-chat is an alias for the plain chat interface. /model opens the model picker; /resources toggles telemetry and /resources full opens the monitor.

Existing sessions remain in each workspace's .hugpy_wrapper/chat directory for compatibility. Reopen using the same --workspace and /session. Removal (sudo apt remove hugpy-harness) leaves chat history, the wrapper, models, and original Hugpy Agent untouched. Purge removes only this package's runtime, not workspace data. The wrapper never installs this optional package.

Chat accepts plain replies; tools are optional when the request needs them. Each user message has its own bounded agent loop. Empty answers and engine errors are reported without demanding a tool call.

Model tools

The harness imports the standalone hugpy_tools catalog. Core file, search, text, data, hash, time, and web tools are available automatically in both the full-screen interface and plain chat. Schemas reach models through prompted tool instructions or native function calling, and results feed back into the conversation through the existing journaled loop.

Existing fs_read, fs_write, fs_glob, and shell calls remain supported. The harness keeps its workspace-relative fs_glob(pattern) contract when the portable catalog contains the same name. File arguments are resolved inside --workspace; writes, network requests, and host operations use --policy (ask by default). Tools execute on the harness machine, even when the model runs on a remote wrapper or fleet.

hugpy-harness --workspace /path/to/project
hugpy-harness chat --workspace /path/to/project --policy readonly
# Add optional document, media, rendering, image, desktop, and VM tools:
hugpy-harness --workspace /path/to/project --optional-tools
hugpy-harness chat --workspace /path/to/project --optional-tools

Optional tools load their backends only when called. Install the relevant hugpy-tools extras in the harness environment, for example pip install 'hugpy-tools[images,files,render]'; rendering also needs Playwright Chromium, and desktop/VM tools need the corresponding host software. Missing backends return a tool error to the model. Generated image and screenshot outputs default to .hugpy_wrapper/tool-artifacts inside the workspace.

Python installations require hugpy-tools>=0.2.7. The Debian build bundles the core tools wheel alongside the harness wheel and installs both offline. Neither mode requires a Toolserver service. Optional backend dependencies are not bundled. To install the unreleased workspace versions together:

pip install ../hugpy_tools .