Harnesses#

Program packages appear under Abilities → Programs → Packages. Tools and Workflows are their callable capabilities; software Applications have a separate management page. New clones use programs/packages/. Previously registered programs/applications/ checkouts retain their locations and call names; upgrading or removing them uses their recorded locations. No source is downloaded or moved just to rename its category.

A harness (an agentic program) is a self-contained git repo of agentic functions. Every supported release already contains the GUI, Research, and Wiki first-party Program packages and their supported runtime assets. The GUI package is installed without PyTorch, OpenCV, or EasyOCR, as described below. openprogram programs install is for additional third-party Programs or developer source overlays; it is not a step required to complete a release installation. The immutable product runtime rejects in-place Program install, upgrade, and uninstall operations.

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 are already present:
openprogram programs available

# Add a third-party harness in a mutable extension/development environment:
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 <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#

For a third-party Program or developer source overlay, the command performs four steps:

1. Shallow-clone the repo into openprogram/programs/packages/<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 Agent method executions fire, and the functions appear in chat / the Programs 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)#

Release users do not run programs install all, a first-run Program wizard, or the GUI harness asset installer. Developers may replace a first-party Program with an editable checkout or configure a different OCR/browser backend; those overlays add development behavior without changing the product manifest.

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 "from openprogram.programs._programs import packages_dir; print(packages_dir())"

git clone <repo-url> /path/to/Harness-Name
openprogram programs install file:///path/to/Harness-Name
# 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 "<PACKAGES>/Harness-Checkout"
openprogram programs install file:///path/to/your/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#

• Supported CLI/server release hosts are macOS, Linux, and Windows x86_64/arm64. Windows Desktop is supported on both architectures. Sandboxed command execution on Windows uses optional WSL2 plus bubblewrap.
• These Program commands require a mutable environment. They work in a source-development checkout and may be used by a CLI release only when its release notes explicitly support Program mutation. Packaged desktop builds refuse the mutation commands until Programs have isolated external environments.
• No symlinks are required in a supported mutable environment: the installer records a real checkout under <PACKAGES> by default.
• A harness can still be platform-specific in its own code (e.g. a desktop-GUI harness may only implement macOS / Linux backends). Whether installation and every function run on a supported host depends on the harness's declared dependencies and platform support; 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 PROGRAM_ENTRIES = [...]

The registration entry point is the agentics sub-package — at startup OpenProgram imports <package>.agentics; that import fires the Agent method executions, 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 import Agent




PROGRAM_ENTRIES = [my_tool]

class ExampleAgent(Agent):
    method_options = {
        'my_tool': {'tool': True},
    }

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

_example_agent = ExampleAgent()
my_tool = _example_agent.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
       PROGRAM_ENTRIES = [my_tool]
   except ImportError:
       PROGRAM_ENTRIES = []
   

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 PROGRAM_ENTRIES
• 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.