Hugpy Harness

hugpy-harness has two roles:

1. A terminal client. It provides a full-screen TUI (hugpy-harness) and a plain chat REPL (hugpy-chat) for a standalone Hugpy wrapper or a Hugpy fleet core such as https://dev.hugpy.ai. It talks HTTP only. It needs no background service, engine, worker enrollment or toolserver.
2. The agent-loop core library. Since 0.1.7, hugpy-agent is built on this package. Its loop, gateway, adapter, journal, policy, memory and tool registry are the harness modules, and hugpy-agent adds its fleet extras through hooks. The harness never imports hugpy-agent.

The full reference, covering hooks, chat-loop behavior and the agent layer, is in docs/agent-and-harness.md.

Status (2026-10-15)

Install

From the apt repo, on any Debian or Ubuntu box:

curl -fsSL https://dev.hugpy.ai/apt/setup.sh | sudo bash
sudo apt install hugpy-harness            # hugpy-wrapper is Recommended, not required
sudo apt install --no-install-recommends hugpy-harness   # client only (remote wrapper/fleet)

From locally built debs, without an apt repo:

bash packaging/debian/build.sh            # -> build/debian/: harness .deb, wrapper .deb if built, install.sh
cd build/debian
./install.sh                              # missing local wrapper: prompt [Y/n]
./install.sh --yes                        # default yes, no prompts
./install.sh --without-wrapper            # harness only (remote wrapper or fleet)
./install.sh --dry-run                    # show the APT plan only

From source with pip:

pip install ../hugpy_tools .              # needs hugpy-tools>=0.2.7

How the deb is put together:

• The deb (Architecture all) carries the harness wheel and the hugpy-tools wheel in /usr/share/hugpy-harness/. The postinst installs both offline into /opt/hugpy-harness/venv.
• /usr/bin/hugpy-harness and /usr/bin/hugpy-chat exec that venv.
• Recommends: hugpy-wrapper (>= 0.1.62). The wrapper keeps its own runtime and service, and neither package embeds the other.
• apt remove hugpy-harness leaves chat history, the wrapper, models and hugpy-agent untouched. A purge removes only this package's runtime.

Connect

If you do not pass --base, the endpoint is resolved in this order, and the first match wins. The fleet entries (4–6) are new in 0.1.8.

1. HUGPY_WRAPPER_URL
2. ~/.config/hugpy/wrapper.endpoint.json (honors XDG_CONFIG_HOME)
3. /etc/hugpy/wrapper.endpoint.json
4. HUGPY_FLEET_URL
5. ~/.config/hugpy/fleet.endpoint.json
6. /etc/hugpy/fleet.endpoint.json, for example {"url": "https://dev.hugpy.ai"}

If nothing is found, the CLI tells you to pass --base URL or set HUGPY_FLEET_URL.

Key. The CLI sends HUGPY_WRAPPER_API_KEY, or else HUGPY_FLEET_API_KEY. The fleet key is a hugpy-core keys create --name <box> --scope use key, and you need it only from outside the LAN once the core requires keys for outside callers. That core key policy is being set up. As of 2026-10-15, the fleet's /v1 answered without a key.

URLs. A bare host gets https://, and {base}/v1 is probed first.

--config FILE reads a JSON connection file that may hold only base and model (both strings). The option's help text says the file comes from fitevict setup, but the installed wrapper CLI (0.1.122) has no setup command, so write the file yourself.

To connect a remote box to the fleet:

echo '{"url":"https://dev.hugpy.ai"}' | sudo tee /etc/hugpy/fleet.endpoint.json
hugpy-chat --list-models
hugpy-harness --model <id from the list>

With 0.1.7, which is what apt serves until 0.1.8 is published, pass --base https://dev.hugpy.ai instead. 0.1.7 does not read the fleet endpoint files or HUGPY_FLEET_API_KEY.

Launch

hugpy-harness                                   # full-screen TUI (same as `launch` / `tui`)
hugpy-harness launch --workspace /path/to/project --model MODEL_ID
hugpy-harness --base http://HOST:PORT --workspace /path/to/project
hugpy-harness chat --model MODEL_ID             # plain REPL (= hugpy-chat)
hugpy-chat --message "one question" --model MODEL_ID   # one turn, exit code 0 on success

TUI options: --config, --base, --workspace, --model, --session, --policy {ask,readonly,auto} (default ask), --optional-tools and --list-models. The model defaults to HUGPY_WRAPPER_MODEL.

hugpy-chat options: the same as the TUI, plus --tools-mode {prompted,constrained,native,auto}, --max-steps (12), --max-tokens (1024), --message and --resume RUN_ID.

In the TUI:

• /model opens the model picker. Every picker filters as you type.
• /resources toggles telemetry, and /resources full opens the compute monitor.
• In the monitor, e or Delete evicts a model through the wrapper's operator action. A fleet core has no eviction route, so there the TUI says so instead of failing.
• The display shows fleet resource snapshots per worker, including stale or offline state.

Sessions are journaled in <workspace>/.hugpy_wrapper/chat/journal.db. Reopen a session with the same --workspace and /session, or use hugpy-chat --resume RUN_ID. Conversations stay in the same workspace journal when you change endpoints.

Chat behavior

Chat runs the agent loop in conversation mode:

• A plain-text reply is a complete answer. Tools are optional.
• Each user message gets its own step budget.
• An empty reply or an engine error ends the turn with that error. The loop never demands a tool call.
• <tool_call> and <tool_response> markup never shows up as reply text.
• A final_answer call that has no answer gets one repair prompt.

Model tools

The harness imports the standalone hugpy_tools catalog, so file, search, text, data, hash, time and web tools work in both the TUI and plain chat. Without optional tools, a loop has 36 tools, including fs_read, fs_write, fs_glob, shell, ask_operator and final_answer.

• Tools execute on the harness machine, jailed to --workspace, even when the model runs on a remote wrapper or fleet.
• Writes, network access and host operations go through --policy.
• --optional-tools adds document, media, rendering, image, desktop and VM tools. Their backends load only when called; install the matching hugpy-tools extras, for example pip install 'hugpy-tools[images,files,render]'. Rendering also needs Playwright Chromium.
• Generated images and screenshots go to .hugpy_wrapper/tool-artifacts in the workspace.

Using the core as a library

from hugpy_harness.config import Config
from hugpy_harness.loop import AgentLoop

loop = AgentLoop(Config(base="http://127.0.0.1:52017", model="MODEL", workspace="."),
                 extra_tool_providers=[my_provider])     # provider(ctx) -> [ToolSpec]
print(loop.run("task"))

The hooks are:

Details and caveats are in docs/agent-and-harness.md.

Development

python -m pytest -q tests          # 20 tests, offline
bash packaging/debian/build.sh     # runs plain `python3`; BUILD_PYTHON is not read (pure-Python wheels)

Build, release and test conventions for the whole tree are in docs/development.md.

Changes

0.1.8 (2026-10-15; installed on ae, not yet in the apt pool)

• Fleet connection. Endpoint resolution falls back to HUGPY_FLEET_URL, then ~/.config/hugpy/fleet.endpoint.json, then /etc/hugpy/fleet.endpoint.json. The key falls back to HUGPY_FLEET_API_KEY. When no endpoint is found, the error now names --base and HUGPY_FLEET_URL.
• Evicting a model on a fleet core (no /v1/operator/actions) reports "this endpoint has no eviction" instead of a raw HTTP error.

0.1.7 (2026-10-15; apt, bundled in hugpy-agent 0.1.118)

• The harness became the core library for hugpy-agent. 0.1.7 added rag_factory, comms_factory, catalog_provider and extra_tool_providers on AgentLoop, the turn_ctx method, Gateway.request_ctx, Config.state_dir and state_path(), the hugpy_harness.tools entry-point group, and the imports/ layer, which includes SERVICE_NAME.

0.1.6 (2026-10-14; PyPI)

• The right-hand resources pane shows one box per loaded model, and e or Delete unloads a model.
• The sessions pane lists the loaded models each session used.
• A model is strictly per session.
• Tool markup (<tool_call> and <tool_response>) is gated out of reply text.

0.1.5 (2026-10-14)

• Pickers search as you type.
• /resources full is the compute panel in the terminal, with eviction.
• A local model's reply is no longer shown twice.