Skip to content

Installation

SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

Installation

Every local install needs Python 3.11 or newer, including its venv module. No installer downloads Python for you. The npm, yarn, bun and pnpm routes also need Node.js 18 or newer, which only runs the launcher.

Route Needs Best for
GitHub installer Python 3.11+ Most people. No Node, npm, Git or administrator access
npm, yarn, bun or pnpm Python 3.11+ and Node.js 18+ People who already manage command-line tools with a Node package manager
A clone Python 3.11+ and Git Working on the harness itself

To try it before installing anything, use the hosted demo.

Install directly from GitHub

On Linux or macOS (Bash and curl):

curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash

On Windows (PowerShell):

irm https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.ps1 | iex

You can also download and read the scripts before running them. They download the shared Python installer completely, then run it. It resolves main to a full commit ID, downloads that source archive, and installs the runtime dependencies in an isolated environment. When uv is on your PATH it installs them, copying files rather than linking them out of its cache, and pip does otherwise, or if uv fails. With no Python 3.11+ on your PATH, the scripts also ask uv for one it already has, and never download one.

Where it puts things

  • The source goes under ~/.local/share/venastine/app.
  • The venastine command goes in ~/.local/bin (venastine.cmd on Windows).
  • The Python environments go in ~/.config/venastine/runtime/github-*.

When ~/.local/bin is not on your PATH yet, the installer puts it there for the terminals you open afterwards:

  • Windows: it appends it to your user PATH, and to the PowerShell window that ran the installer.
  • macOS and Linux: it adds a marked block to your shell's startup file: ~/.zshrc, ~/.bashrc, fish's conf.d/venastine.fish, or ~/.profile for other shells, plus the bash login file you already have on macOS.

Running it again adds nothing twice. To leave PATH alone, set VENASTINE_NO_MODIFY_PATH=1 or pass --no-modify-path. If another venastine (an npm install, say) comes first on your PATH, the installer names it and prints the new command's full path instead.

Credentials and conversation state follow the same rules as an npm install: keys in ~/.config/venastine/providers.json unless the directory you are in has its own, and threads and memories in ~/.config/venastine/.

Options

Set these before running either command.

Variable What it does
VENASTINE_REF Install a branch, tag or full commit ID instead of main. Refs older than the installer (without bin/venastine.py) cannot use it
VENASTINE_INSTALL_DIR Where the source goes
VENASTINE_BIN_DIR Where the venastine command goes
VENASTINE_PYTHON Which Python executable to use
VENASTINE_NO_MODIFY_PATH=1 Leave PATH alone
VENASTINE_NO_UV=1 Install with pip even when uv is on your PATH

The installer itself always comes from main, even when you choose another source ref. Bash can also pass options straight through:

curl -fsSL https://raw.githubusercontent.com/YahyaHammad/Venastine-Research-Harness/main/install.sh | bash -s -- --ref main

From a checkout, python scripts/install.py --help lists the same options without downloading or installing anything.

Updating

Close any running Venastine sessions, then run the installer again. It builds a fresh environment before replacing the active source, and carries your config.yaml edits forward. Previous source trees (previous-*) stay under the install directory for recovery, so updates use more disk space over time. An unrelated existing directory or command is never replaced.

Uninstalling

Remove these four things:

  1. the venastine command;
  2. the install directory;
  3. the github-* runtime directories it created under ~/.config/venastine/runtime;
  4. the PATH entry it added: from your user PATH on Windows, or the block between the venastine GitHub installer markers in your shell's startup file.

Your other state in ~/.config/venastine (keys, settings, conversations and memories) and the reports in your projects stay until you delete them. PRIVACY.md lists every file the harness keeps.

From npm

npm install -g @yahyahammad/venastine

npm handles the setup for you. It delivers the harness as a folder of source, with no bundled binary, and Python still runs it, so the only thing you provide is an interpreter on PATH. The rest happens on first launch: the launcher finds a suitable Python, tells you which one and what it is about to install, and builds an isolated environment with the pinned dependencies once you agree, with uv when it is on your PATH. It asks every time it would install something, never installs during npm install itself, and refuses rather than proceeding when there is no terminal to ask in.

Two things differ from a clone, both so that a command you run from anywhere behaves sensibly:

  • Credentials fall back to ~/.config/venastine/providers.json when the directory you are in has no providers.json of its own. A local one still wins, so per-project keys keep working.
  • Conversation state (app.db and the log) lives in ~/.config/venastine/, so threads and memories follow you between directories. Research reports still land in ./output beside the work that produced them, and the file tools' workspace stays in the current directory, because it is a permission boundary.

Updating keeps your settings. npm update -g @yahyahammad/venastine replaces the package directory, config.yaml with it, so the launcher merges your own values back in before the harness starts and prints what it kept. Settings you never touched pick up the new version's defaults. A value the new version no longer accepts is dropped and named, rather than costing you the rest. The one case it cannot help with is an edit made after your last session and never launched before you updated.

To uninstall, run npm uninstall -g @yahyahammad/venastine. Your state in ~/.config/venastine stays until you delete it.

With yarn, bun or pnpm

The same package installs from the npm registry with the other package managers, and everything above about the launcher applies to each.

yarn global add @yahyahammad/venastine
bun add -g --backend=copyfile @yahyahammad/venastine
pnpm add -g --config.package-import-method=copy @yahyahammad/venastine

To update, run the same command with @latest after the package name.

  • yarn means Yarn 1 (classic). Yarn 2 and later have no global install.
  • bun and pnpm need the copy flag, on updates too. By default both hardlink the package's files out of a shared cache or store. The harness protects its own source from tool writes, and a hardlink would give that source a second name in a folder it does not protect. The flag makes them copy, as npm and yarn do.
  • pnpm does not carry config.yaml edits across an update. It puts every install in a new directory, and the harness keys your saved config.yaml values by that directory, so after an update the values you set with /config or by editing the file are back at the shipped defaults. What lives in ~/.config/venastine (settings.json, keys, conversations and memories) is unaffected. If you rely on config.yaml edits, install with npm, yarn or bun instead.

From a clone

git clone https://github.com/YahyaHammad/Venastine-Research-Harness.git
cd Venastine-Research-Harness
pip install -r requirements.txt

This is the contributor route, and the one the README's examples assume (python main.py). Two extras are optional:

  • pip install -e ".[documents]" adds markitdown, which lets the read tool convert PDF, DOCX, PPTX, XLSX and HTML files to Markdown. read is off by default (see Tool Permissions).
  • pip install -e ".[pdf]" adds the PDF export of research reports.

Then create the two credential files from their templates:

cp providers.json.example providers.json   # then add your model provider's API key
cp .env.example .env                       # then fill in only the keys your tools need

They are kept apart on purpose: providers.json holds model provider keys, read by one module at model-call time, and .env holds tool API keys (a GitHub token, an NVD key), handed to code that talks to third parties. Both are gitignored. In the TUI, /connect writes providers.json for you (see Getting Started).

To run the test suite, install requirements-test.txt too and run pytest. It is fully offline and needs no API keys.

Check your install

venastine --venastine-doctor

It prints the installed version, the commit, the interpreter and the paths the harness uses. An npm-family install prints the path of config.yaml itself; a GitHub install prints its package root, and config.yaml is the file at the top of it. In a clone, it is config.yaml at the top of the checkout. That is the file to edit when a guide here says to change a config.yaml setting.

Next: Getting Started.

Checked against release 0.3.12 (commit f33ef8a). The README's Setup section is the reference.

Clone this wiki locally