Harnesses#

A harness (an agentic program) is a self-contained git repo of agentic functions. openprogram programs install records its source under openprogram/functions/agentics/, and its functions then register like built-ins. This is a general mechanism: the first-party programs (gui / research / wiki) and any third-party repo install the exact same way. Cross-platform (macOS / Linux / Windows); no symlinks required.

Where the agent reads this: this file is the canonical procedure. When a user asks to install a harness the agent doesn't have, follow the steps below — they're written to be executed step by step.

TL;DR#

# First-party programs — by name:
openprogram programs install research      # light (no extra deps)
openprogram programs install gui           # heavy (pulls torch/opencv)

# ANY third-party harness — same command, by git source:
openprogram programs install https://github.com/<owner>/<Harness-Name>
openprogram programs install <owner>/<Harness-Name>     # GitHub shorthand

# Manage:
openprogram programs available             # status, incl. third-party
openprogram programs uninstall research    # first-party: by name
openprogram programs uninstall <Harness-Name>   # third-party: by dir name
openprogram programs install <ref> --upgrade    # git pull + re-resolve deps

# …restart OpenProgram. Done — the functions self-register.

Part 1 — Using harnesses#

What programs install does#

The same four steps for first-party and third-party:

1. Shallow-clone the repo into openprogram/functions/agentics/<Repo-Name>/ — a real, editable directory (not site-packages). The clone is git-ignored by OpenProgram, so it stays an independent checkout you can git pull or edit in place.
2. Install the harness's own declared dependencies — the harness is self-describing: its pyproject.toml/setup.py (preferred) or requirements.txt is installed. OpenProgram carries no per-harness dependency lists.
3. Verify the contract — the clone must contain a package with agentics/__init__.py (see Part 2). A repo that doesn't match is reported and will simply not register; it never breaks the load.
4. Record the owner-approved source. On the next launch the registry imports only recorded <package>.agentics packages, the @agentic_function decorators fire, and the functions appear in chat / the Functions page / openprogram programs run.

Guard rails: for an existing dev symlink, install verifies the harness contract and records the link without modifying its target. It refuses a same-named non-git directory. uninstall on a symlink removes only the link, never the checkout it points to.

First-party programs (gui / research / wiki)#

openprogram programs install all installs the three; the first-run setup wizard's "Agent programs" step offers the same choice interactively.

GUI agent — one extra step. Beyond its pip deps, gui_agent needs a YOLO detector weight + OCR models that aren't on PyPI. After the install, run the harness's own installer to fetch them (it skips the host since you already have it): openprogram/functions/agentics/GUI-Agent-Harness/scripts/install.sh --no-host (Windows: …\scripts\install.ps1 -NoHost). See the GUI install guide.

Third-party harnesses#

Anyone's harness repo installs with the same command — no catalogue edit, no registration step anywhere:

openprogram programs install https://github.com/<owner>/<Harness-Name>
openprogram programs install <owner>/<Harness-Name>   # GitHub shorthand
openprogram programs install file:///path/to/checkout # local git source

openprogram programs available lists installed third-party harnesses with their contract status; openprogram programs uninstall <Harness-Name> removes one by its clone-dir name.

python -c "import openprogram,os;print(os.path.join(os.path.dirname(openprogram.__file__),'functions','agentics'))"

git clone <repo-url> "<AGENTICS>/<Harness-Name>"
pip install "<AGENTICS>/<Harness-Name>"        # or its requirements.txt
# restart OpenProgram

Developer setup (work on a harness you're writing)#

Symlink your working checkout instead of cloning a copy:

ln -s /path/to/your/Harness-Checkout "<AGENTICS>/Harness-Checkout"

Edits take effect on the next restart; programs install will refuse to overwrite the link, and programs uninstall <name> removes only the link. (Windows note: symlinks need developer mode — cloning a real directory is the supported path there.)

Verify an install#

openprogram programs available     # install status (first- and third-party)
openprogram programs list          # all registered functions

To see why a present-but-broken harness didn't load:

OPENPROGRAM_DEBUG_REGISTRY=1 openprogram programs list

(Windows PowerShell: $env:OPENPROGRAM_DEBUG_REGISTRY=1; openprogram programs list)

Then use it — the harness's functions are callable like any built-in (in chat, or openprogram programs run <fn> -a key=value).

Platform notes#

• Base install is one command, every OS: clone OpenProgram and run ./scripts/install.sh (Windows: .\scripts\install.ps1).
• No symlinks needed — cloning a real directory into <AGENTICS> is the supported path, so there's no Windows admin/developer-mode hurdle.
• A harness can still be platform-specific in its own code (e.g. a desktop-GUI harness may only implement macOS / Linux backends). Installing always works; whether every function runs on your OS is the harness's concern — check its README.
• Encoding / paths: OpenProgram's own tooling is UTF-8 and os.path-based throughout; a well-behaved harness should be too.

Troubleshooting#

Part 2 — Writing your own installable harness#

Any repo that satisfies one layout contract becomes a one-command install for every OpenProgram user.

The contract#

<Harness-Name>/                      ← the repo (any name)
├── pyproject.toml                   ← declares the harness's OWN deps only
└── <package>/                       ← an importable package (ascii name)
    ├── __init__.py                  ← kept dependency-light
    └── agentics/
        └── __init__.py              ← exposes AGENTIC_FUNCTIONS = [...]

The registration entry point is the agentics sub-package — at startup OpenProgram imports <package>.agentics; that import fires the @agentic_function decorators, which self-register into the shared registry. The harness root may also vendor other packages — discovery finds the one with an agentics/ sub-package and puts the harness root on sys.path, so the harness's own absolute imports (from <package>.foo import bar) resolve.

Minimal working template#

# <package>/agentics/__init__.py
from openprogram.agentic_programming.function import agentic_function


@agentic_function
def my_tool(text: str = "") -> str:
    "One line: what this does (shown in catalogs)."
    return text.upper()


AGENTIC_FUNCTIONS = [my_tool]

# <package>/__init__.py
"""My harness — keep this import-light (see hard rule 2)."""

# pyproject.toml
[project]
name = "my-harness"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []          # the harness's own deps — NEVER openprogram

That's a complete installable harness.

Two hard rules#

1. Never declare openprogram as a dependency (in pyproject.toml or requirements.txt). The harness runs inside an existing OpenProgram install; a declared openprogram @ git+… would make pip re-install the host from git, clobbering the user's local (often editable) install.

2. Keep the top-level <package>/__init__.py dependency-light, and guard heavy imports in agentics/__init__.py. Discovery imports <package>.agentics on every startup, including on machines that haven't installed your optional/heavy deps — a top-level import of cv2/torch/etc. would break the whole registry load. Lazy-import heavy modules inside function bodies, and guard the entry import:

   # agentics/__init__.py — deps-less machines must not break the load
   try:
       from my_package.main import my_tool
       AGENTIC_FUNCTIONS = [my_tool]
   except ImportError:
       AGENTIC_FUNCTIONS = []
   

The three first-party harnesses follow this exact shape — read any of them as a working template.

Test locally before publishing#

The install command accepts a file:// source, so the full user flow is testable against your local checkout:

cd /path/to/My-Harness && git add -A && git commit -m wip
openprogram programs install file:///path/to/My-Harness
openprogram programs available        # should show: My-Harness [ok] (package: …)
OPENPROGRAM_DEBUG_REGISTRY=1 openprogram programs list   # functions present?
openprogram programs run my_tool -a text=hello           # smoke test
openprogram programs uninstall My-Harness                # clean up

Checklist before you publish:

• <package>/agentics/__init__.py exposes AGENTIC_FUNCTIONS
• no openprogram in pyproject/requirements (hard rule 1)
• python -c "import <package>.agentics" succeeds in a bare venv with only OpenProgram installed (hard rule 2)
• file:// install round-trip above passes

Publish#

Push to GitHub. Users install with:

openprogram programs install <owner>/<Harness-Name>

Nothing to register anywhere — the repo URL is the distribution.