Installation#

The model — read this first#

OpenProgram is the host. You install it once, then add agent programs into it.

OpenProgram  (the host runtime — install this first, anywhere you like)
└── openprogram/functions/agentics/      ← owner-installed programs live here
    ├── GUI-Agent-Harness/               ← `gui_agent`      (clone in + run its installer)
    ├── Research-Agent-Harness/          ← `research_agent` (openprogram programs install research)
    └── Wiki-Agent-Harness/              ← `wiki_agent`     (openprogram programs install wiki)

A program installed with openprogram programs install is source-recorded and registered at launch (import_installed_programs() imports its agentics sub-package, firing the @agentic_function decorator), so it appears in the web UI and function list. An unrecorded directory is not imported. Install order is therefore always: OpenProgram first, then the program(s).

⚠️ Installing just the Python package is not the whole job — it doesn't build the web UI (needs npm), fetch the GUI agent's model weight, or warm the OCR models. The install script below is the source of truth — it does everything.

One command (recommended)#

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.sh | bash
# from a checkout: ./scripts/install.sh   # everything · bare host: --minimal

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.ps1 | iex
# from a checkout: .\scripts\install.ps1   # everything · bare host: -Minimal

When not run from a checkout, the script first clones the repo to ~/OpenProgram (change with --target DIR), then hands off to the install. The default install brings up everything light in the host: web UI (built), terminal UI, browser tool + channels. Agent programs (GUI / Research / Wiki) are not part of the default install — with a terminal attached the script shows a menu to pick them, or add them later with openprogram programs install <research|wiki|gui> (GUI downloads PyTorch), or via openprogram setup → programs. --minimal installs a bare host instead.

Then just start it — the first run walks you through provider setup, then opens the chat:

openprogram                                   # first run = guided provider setup, then chat
openprogram web                               # or the browser UI -> http://localhost:18100

The installer is idempotent — re-run it any time to repair or update.

What the installer does#

Flags#

The full flag matrix (install.sh --help prints it; the PowerShell flags are documented at the top of install.ps1):

Explicit CUDA/CPU PyTorch for the GUI harness: run its own installer after the host install — openprogram/functions/agentics/GUI-Agent-Harness/scripts/install.sh --cuda cu124.

Non-interactive / AI-agent installs#

For agent-driven installs, no special flags are needed: the curl … | bash one-liner already runs unattended. Without a terminal (piped, CI) it takes the defaults automatically; even with a terminal, every /dev/tty read has a 60-second timeout that falls back to the default (printing a one-line (no input in 60s — using default)) — so no prompt can hang forever. Change the timeout with OPENPROGRAM_PROMPT_TIMEOUT=<seconds>.

To take the defaults immediately instead of waiting out the timeout, add --yes / -y; to also install agent programs non-interactively, add --programs all (or gui / research / wiki). These environment variables are equivalent to --yes — if any matches, all defaults are taken and no prompt is shown:

Fully non-interactive, with agent programs included, in one command:

curl -fsSL https://raw.githubusercontent.com/Fzkuji/OpenProgram/main/scripts/install.sh | bash -s -- -y --programs all

Windows' Read-Host has no timeout mechanism, so install.ps1 prompts do not fall back to defaults on their own — on Windows an agent must pass -Yes or set one of the environment variables above.

Adding agent programs#

Programs installed through the CLI land in functions/agentics/<Repo>/ and register on the next start. The same command works for bundled harnesses and third-party repositories; run a harness-specific installer afterward when it has additional assets:

openprogram programs install <harness-repo>
cd openprogram/functions/agentics/<Harness>
./scripts/install.sh          # if it ships one (Windows: .\scripts\install.ps1)

The GUI agent has native deps (PyTorch, detector weight, OCR), so it ships its own per-platform installer — use it via the steps above; full guide in its install section. (When GUI is opted in — checked in the menu, or --programs gui/all — the install script clones it and pulls PyTorch; run the harness's own installer afterwards for its asset setup or an explicit CUDA/CPU torch.)

For the bundled harnesses there's a one-line shortcut that clones, installs, and registers them for you:

openprogram programs install research     # or: wiki / gui / all
openprogram programs available            # see install status

programs install clones the repo and pip-installs its declared deps (non-editable: deps go to site-packages, the code runs in-tree). For gui that includes PyTorch, but not native assets like the YOLO weight or the OCR warm-up — run the GUI harness's own installer (above) for those.

After any of these, restart the worker (or hit Refresh on the Functions page) and the program shows in the web UI. Third-party harnesses install the same way — openprogram programs install <git-url | owner/repo>; details: installing-harnesses.md.

Extras#

The browser tool + chat channels install by default (the [all] extra), and the installer fetches the Playwright Chromium binary for you — nothing to opt into. Pass --minimal / -Minimal to skip them (e.g. CI / air-gapped / bandwidth-limited).

Heavier, still opt-in (add the flag):

Provider SDKs (anthropic, openai, google-genai) ship in the base install — no extra needed.

Providers / credentials#

At least one provider is required before any chat turn:

openprogram providers login openai-codex      # ChatGPT subscription (recommended)
openprogram providers login anthropic          # Claude
export ANTHROPIC_API_KEY=sk-ant-...             # …or an API key (Windows: $env:ANTHROPIC_API_KEY="...")

Auto-adopts an installed Claude Code / Codex / Gemini CLI. Check with openprogram doctor.

Ports#

One port serves everything — the FastAPI worker hosts the API, the WebSocket, and the web UI static export:

Change with openprogram ports --port <p> (or OPENPROGRAM_WEB_PORT for one run).

Full dependency matrix#

Everything beyond pip. The installer handles every "auto" row.

Host (OpenProgram)#

GUI-Agent-Harness program (opt-in — once selected; see Adding agent programs)#

* EasyOCR is installed as a cross-platform fallback, so the GUI agent works on macOS without Xcode CLT — Apple Vision is just faster. Full GUI specifics: GUI-Agent-Harness/docs/install.md.

Troubleshooting#

• openprogram web showed a page that won't load. The web UI static export (web/out/) wasn't built — the web/ node_modules weren't installed. Re-run the installer, then open http://localhost:18100.
• pip can't reinstall: WinError 32 … openprogram.exe is being used. Stop the running openprogram web / worker first, then re-run.
• gui_agent doesn't appear in the UI. Restart the worker (or Refresh the Functions page). Confirm it's registered: openprogram programs available.
• NVIDIA GPU unused. The installer auto-detects it; if it picked CPU (no driver at install time, or you passed --cpu): pip uninstall -y torch torchvision, then re-run the installer.
• GPA weight didn't download (offline): hf download Salesforce/GPA-GUI-Detector model.pt --local-dir ~/GPA-GUI-Detector.

Manual / advanced#

python -m venv .venv && . .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e .                                  # host
( cd web && npm install )                         # web UI
( cd cli && npm install && npm run build )         # TUI (POSIX)
# GUI program (editable, in-tree → auto-registers):
pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install -e "openprogram/functions/agentics/GUI-Agent-Harness[ocr]"
hf download Salesforce/GPA-GUI-Detector model.pt --local-dir ~/GPA-GUI-Detector
python -c "import easyocr; easyocr.Reader(['en','ch_sim'], gpu=False)"

Multi-repo local development (editing several harnesses side-by-side): troubleshooting.md → Local-development install.